PSR-4 自动加载规范 - 示例文档

PSR-4 的实现示例

下面的示例说明了符合 PSR-4 的代码：

闭包示例

  1. <?php
  2. /**
  3.  * 一个具体项目实现的示例。
  4.  *
  5.  * 在注册自动加载函数后，下面这行代码将引发程序
  6.  * 尝试从 /path/to/project/src/Baz/Qux.php
  7.  * 加载 \Foo\Bar\Baz\Qux 类：
  8.  *
  9.  *      new \Foo\Bar\Baz\Qux;
  10.  *
  11.  * @param string $class 完全标准的类名。
  12.  * @return void
  13.  */
  14. spl_autoload_register(function ($class) {
  16.     // 具体项目的命名空间前缀
  17.     $prefix = 'Foo\\Bar\\';
  19.     // 命名空间前缀对应的基础目录
  20.     $base_dir = __DIR__ . '/src/';
  22.     // 该类使用了此命名空间前缀？
  23.     $len = strlen($prefix);
  24.     if (strncmp($prefix, $class, $len) !== 0) {
  25.         // 否，交给下一个已注册的自动加载函数
  26.         return;
  27.     }
  29.     // 获取相对类名
  30.     $relative_class = substr($class, $len);
  32.     // 命名空间前缀替换为基础目录，
  33.     // 将相对类名中命名空间分隔符替换为目录分隔符，
  34.     // 附加 .php
  35.     $file = $base_dir . str_replace('\\', '/', $relative_class) . '.php';
  37.     // 如果文件存在，加载它
  38.     if (file_exists($file)) {
  39.         require $file;
  40.     }
  41. });

类示例

以下是一个可处理多命名空间的类实现示例：

  1. <?php
  2. namespace Example;
  4. /**
  5.  * 一个多用途的示例实现，包括了
  6.  * 允许多个基本目录用于单个
  7.  * 命名空间前缀的可选功能
  8.  *
  9.  * 下述示例给出了一个 foo-bar 类包，系统中路径结构如下……
  10.  *
  11.  *     /path/to/packages/foo-bar/
  12.  *         src/
  13.  *             Baz.php             # Foo\Bar\Baz
  14.  *             Qux/
  15.  *                 Quux.php        # Foo\Bar\Qux\Quux
  16.  *         tests/
  17.  *             BazTest.php         # Foo\Bar\BazTest
  18.  *             Qux/
  19.  *                 QuuxTest.php    # Foo\Bar\Qux\QuuxTest
  20.  *
  21.  * ……添加路径到  \Foo\Bar\  命名空间前缀的类文件中
  22.  * 如下所示：
  23.  *
  24.  *      <?php
  25.  *      // 实例化加载器
  26.  *      $loader = new \Example\Psr4AutoloaderClass;
  27.  *
  28.  *      // 注册加载器
  29.  *      $loader->register();
  30.  *
  31.  *      // 为命名空间前缀注册基本路径
  32.  *      $loader->addNamespace('Foo\Bar', '/path/to/packages/foo-bar/src');
  33.  *      $loader->addNamespace('Foo\Bar', '/path/to/packages/foo-bar/tests');
  34.  *
  35.  * 下述语句会让自动加载器尝试从 
  36.  * /path/to/packages/foo-bar/src/Qux/Quux.php 
  37.  * 中加载  \Foo\Bar\Qux\Quux 类
  38.  *
  39.  *      <?php
  40.  *      new \Foo\Bar\Qux\Quux;
  41.  *
  42.  *  下述语句会让自动加载器尝试从 
  43.  *   /path/to/packages/foo-bar/tests/Qux/QuuxTest.php
  44.  * 中加载 \Foo\Bar\Qux\QuuxTest 类：
  45.  *
  46.  *      <?php
  47.  *      new \Foo\Bar\Qux\QuuxTest;
  48.  */
  49. class Psr4AutoloaderClass
  50. {
  51.     /**
  52.      * 关联数组，键名为命名空间前缀，键值为一个基本目录数组。
  53.      *
  54.      * @var array
  55.      */
  56.     protected $prefixes = array();
  58.     /**
  59.      * 通过 SPL 自动加载器栈注册加载器
  60.      *
  61.      * @return void
  62.      */
  63.     public function register()
  64.     {
  65.         spl_autoload_register(array($this, 'loadClass'));
  66.     }
  68.     /**
  69.      * 为命名空间前缀添加一个基本目录
  70.      *
  71.      * @param string $prefix 命名空间前缀。
  72.      * @param string $base_dir 命名空间下类文件的基本目录
  73.      * @param bool $prepend 如果为真，预先将基本目录入栈
  74.      * 而不是后续追加；这将使得它会被首先搜索到。
  75.      * @return void
  76.      */
  77.     public function addNamespace($prefix, $base_dir, $prepend = false)
  78.     {
  79.         // 规范化命名空间前缀
  80.         $prefix = trim($prefix, '\\') . '\\';
  82.         // 规范化尾部文件分隔符
  83.         $base_dir = rtrim($base_dir, DIRECTORY_SEPARATOR) . '/';
  85.         // 初始化命名空间前缀数组
  86.         if (isset($this->prefixes[$prefix]) === false) {
  87.             $this->prefixes[$prefix] = array();
  88.         }
  90.         // 保留命名空间前缀的基本目录
  91.         if ($prepend) {
  92.             array_unshift($this->prefixes[$prefix], $base_dir);
  93.         } else {
  94.             array_push($this->prefixes[$prefix], $base_dir);
  95.         }
  96.     }
  98.     /**
  99.      * 加载给定类名的类文件
  100.      *
  101.      * @param string $class 合法类名
  102.      * @return mixed 成功时为已映射文件名，失败则为 false
  103.      */
  104.     public function loadClass($class)
  105.     {
  106.         // 当前命名空间前缀
  107.         $prefix = $class;
  109.         // 通过完整的命名空间类名反向映射文件名
  110.         while (false !== $pos = strrpos($prefix, '\\')) {
  112.             // 在前缀中保留命名空间分隔符
  113.             $prefix = substr($class, 0, $pos + 1);
  115.             // 其余的是相关类名
  116.             $relative_class = substr($class, $pos + 1);
  118.             // 尝试为前缀和相关类加载映射文件
  119.             $mapped_file = $this->loadMappedFile($prefix, $relative_class);
  120.             if ($mapped_file) {
  121.                 return $mapped_file;
  122.             }
  124.             // 删除 strrpos() 下一次迭代的尾部命名空间分隔符
  125.             $prefix = rtrim($prefix, '\\');
  126.         }
  128.         // 找不到映射文件
  129.         return false;
  130.     }
  132.     /**
  133.      * 为命名空间前缀和相关类加载映射文件。
  134.      *
  135.      * @param string $prefix 命名空间前缀
  136.      * @param string $relative_class 相关类
  137.      * @return mixed Boolean 无映射文件则为false，否则加载映射文件
  138.      */
  139.     protected function loadMappedFile($prefix, $relative_class)
  140.     {
  141.         // 命名空间前缀是否存在任何基本目录
  142.         if (isset($this->prefixes[$prefix]) === false) {
  143.             return false;
  144.         }
  146.         // 通过基本目录查找命名空间前缀
  147.         foreach ($this->prefixes[$prefix] as $base_dir) {
  149.             // 用基本目录替换命名空间前缀
  150.             // 用目录分隔符替换命名空间分隔符
  151.             // 给相关的类名增加 .php 后缀
  152.             $file = $base_dir
  153.                   . str_replace('\\', '/', $relative_class)
  154.                   . '.php';
  156.             // 如果映射文件存在，则引入
  157.             if ($this->requireFile($file)) {
  158.                 // 搞定了
  159.                 return $file;
  160.             }
  161.         }
  163.         // 找不到
  164.         return false;
  165.     }
  167.     /**
  168.      * 如果文件存在从系统中引入进来
  169.      *
  170.      * @param string $file 引入文件
  171.      * @return bool 文件存在则 true 否则 false
  172.      */
  173.     protected function requireFile($file)
  174.     {
  175.         if (file_exists($file)) {
  176.             require $file;
  177.             return true;
  178.         }
  179.         return false;
  180.     }
  181. }

单元测试

以下示例是上述类加载器的单元测试方式之一：

  1. <?php
  2. namespace Example\Tests;
  4. class MockPsr4AutoloaderClass extends Psr4AutoloaderClass
  5. {
  6.     protected $files = array();
  8.     public function setFiles(array $files)
  9.     {
  10.         $this->files = $files;
  11.     }
  13.     protected function requireFile($file)
  14.     {
  15.         return in_array($file, $this->files);
  16.     }
  17. }
  19. class Psr4AutoloaderClassTest extends \PHPUnit\Framework\TestCase
  20. {
  21.     protected $loader;
  23.     protected function setUp(): void
  24.     {
  25.         $this->loader = new MockPsr4AutoloaderClass;
  27.         $this->loader->setFiles(array(
  28.             '/vendor/foo.bar/src/ClassName.php',
  29.             '/vendor/foo.bar/src/DoomClassName.php',
  30.             '/vendor/foo.bar/tests/ClassNameTest.php',
  31.             '/vendor/foo.bardoom/src/ClassName.php',
  32.             '/vendor/foo.bar.baz.dib/src/ClassName.php',
  33.             '/vendor/foo.bar.baz.dib.zim.gir/src/ClassName.php',
  34.         ));
  36.         $this->loader->addNamespace(
  37.             'Foo\Bar',
  38.             '/vendor/foo.bar/src'
  39.         );
  41.         $this->loader->addNamespace(
  42.             'Foo\Bar',
  43.             '/vendor/foo.bar/tests'
  44.         );
  46.         $this->loader->addNamespace(
  47.             'Foo\BarDoom',
  48.             '/vendor/foo.bardoom/src'
  49.         );
  51.         $this->loader->addNamespace(
  52.             'Foo\Bar\Baz\Dib',
  53.             '/vendor/foo.bar.baz.dib/src'
  54.         );
  56.         $this->loader->addNamespace(
  57.             'Foo\Bar\Baz\Dib\Zim\Gir',
  58.             '/vendor/foo.bar.baz.dib.zim.gir/src'
  59.         );
  60.     }
  62.     public function testExistingFile()
  63.     {
  64.         $actual = $this->loader->loadClass('Foo\Bar\ClassName');
  65.         $expect = '/vendor/foo.bar/src/ClassName.php';
  66.         $this->assertSame($expect, $actual);
  68.         $actual = $this->loader->loadClass('Foo\Bar\ClassNameTest');
  69.         $expect = '/vendor/foo.bar/tests/ClassNameTest.php';
  70.         $this->assertSame($expect, $actual);
  71.     }
  73.     public function testMissingFile()
  74.     {
  75.         $actual = $this->loader->loadClass('No_Vendor\No_Package\NoClass');
  76.         $this->assertFalse($actual);
  77.     }
  79.     public function testDeepFile()
  80.     {
  81.         $actual = $this->loader->loadClass('Foo\Bar\Baz\Dib\Zim\Gir\ClassName');
  82.         $expect = '/vendor/foo.bar.baz.dib.zim.gir/src/ClassName.php';
  83.         $this->assertSame($expect, $actual);
  84.     }
  86.     public function testConfusion()
  87.     {
  88.         $actual = $this->loader->loadClass('Foo\Bar\DoomClassName');
  89.         $expect = '/vendor/foo.bar/src/DoomClassName.php';
  90.         $this->assertSame($expect, $actual);
  92.         $actual = $this->loader->loadClass('Foo\BarDoom\ClassName');
  93.         $expect = '/vendor/foo.bardoom/src/ClassName.php';
  94.         $this->assertSame($expect, $actual);
  95.     }
  96. }