Package Development

• 简介
• 创建包
• 包结构
• 服务提供器
• 延迟加载服务提供器
• 包约定
• 开发流程
• 包路由
• 包配置
• 包视图
• 包迁移
• 包Assets
• 发布包

简介

包是向Laravel中添加功能最重要的途径。它通过一种强大的方式几乎可以包含任意功能，比如处理日期的扩展包Carbon，完整的BDD测试框架扩展包Behat.

当然，还有很多不同类型的包。有些包是独立的，这意味着它们可以在任何框架中工作，而不仅仅是Laravel。上面提到的Carbon和Behat就是独立的包。要在Laravel中使用这些包只需要在composer.json文件中指明。

另一方面，有些包仅支持Laravel。在上一个Laravel版本中，这些类型的包我们称为"bundles"。这些包可以增强Laravel应用的路由、控制器、视图、配置和迁移。由于开发独立的包不需要专门的过程，因此，本手册主要涵盖针对Laravel开发独立的包。

所有Laravel包都是通过Packagist和Composer发布的，因此很有必要学习这些功能强大的PHP包发布管理工具。

创建包

为Laravel创建一个包的最简单方式是使用Artisan的workbench命令。首先，你需要在app/confg/workbench.php文件中配置一些参数。在该文件中，你会看到name和email两个参数，这些值是用来为您新创建的包生成composer.json文件的。一旦你提供了这些值，就可以开始构建一个新包了！

执行Artisan的workbench命令

php artisan workbench vendor/package --resources

厂商名称（vendor name）是用来区分不同作者构建了相同名字的包。例如，如果我（Taylor Otwell）创建了个名为"Zapper"的包，厂商名就可以叫做Taylor，包名可以叫做Zapper。默认情况下，workbench命令建的包是不依赖任何框架的；不过，resources命令将会告诉workbench生成关联Laravel的一些特殊目录，例如migrations、views、config等。

一旦执行了workbench命令，新创建的包就会出现在Laravel安装跟目录下的workbench目录中。接下来就应该为你创建的包注册ServiceProvider了。你可以通过在app/config/app.php文件里的provides数组中添加该包。这将通知Laravel在应用程序开始启动时加载该包。服务提供者（Service providers）使用[Package]ServiceProvider样式的命名方式。所以，以上案例中，你需要将Taylor\Zapper\ZapperServiceProvider添加到providers数组。

一旦注册了provider，你就可以开始写代码了！然而，在此之前，建议你查看以下部分来了解更多关于包结构和开发流程的知识。

注意: 如果你的Service providers提示无法找到, 在项目根目录执行php artisan dump-autoload

包结构

执行workbench命令之后，你的包结构将被初始化，并能够与laravel框架完美融合：

包的基本目录结构

/src
    /Vendor
        /Package
            PackageServiceProvider.php
    /config
    /lang
    /migrations
    /views
/tests
/public

让我们来深入了解该结构。src/Vendor/Package目录是所有class的主目录，包括ServiceProvider。config、lang、migrations和views目录，就如你所猜测，包含了你创建的包的相应资源。包可以包含这些资源中的任意几个，就像一个"常规"的应用。

服务提供器

服务提供器只是包的引导类。默认情况下，他们包含两个方法：boot和register。你可以在这些方法内做任何事情，例如：包含路由文件、注册IoC容器的绑定、监听事件或者其他任何你想做的事情。

register方法在服务提供器注册时被立即调用，而boot方法仅在请求被路由到之前调用。因此，如果服务提供器中的动作（action）依赖另一个已经注册的服务提供器，或者你正在覆盖另一个服务提供其绑定的服务，就应该使用boot方法。

当使用workbench命令创建包时，boot方法已经包含了如下的动作：

$this->package('vendor/package');

该方法告诉Laravel如何为应用程序加载视图、配置或其他资源。通常情况下，你没有必要改变这行代码，因为它会根据workbench的默认约定将包设置好的。

默认情况下，一旦注册了一个包，那么它的资源可以通过"package"方法在vendor/package中找到。你也可以向package 方法中传入第二个参数来重写这个方法。例如

//向 `package` 方法中传入一个自定义的命名空间
$this->package('vendor/package', 'custom-namespace');

//现在，这个包的资源现在可以通过这个自定义的命名空间来访问
$view = View::make('custom-namespace::foo');

Laravel并没有为service provider提供“默认”的存放地点。您可以根据自己的喜好，将它们放置在任何地方，您也可以将它们统一组织在一个Providers命名空间里，并放置在应用的app目录下。这些文件可以被放置在任何地方，只需保证Composer的自动加载组件知道如何加载这些类。

如果你改变了你的包得资源的位置，比如配置文件或者视图，你需要在package函数中传递第三个参数，指定你的资源位置

$this->package('vendor/package', null, '/path/to/resources');

延迟加载服务提供器

如果你写了一个服务提供器，但没有注册任何资源，比如配置文件或视图等，你可以选择"延迟"加载你的提供器。延迟加载的服务提供器在这个服务真正被IoC容器需要的时候才会被加载和注册。如果这个服务提供器没有被当前的请求路由需要，那么这个提供器永远不会被加载

如果想延时载入你的服务提供器，只需要在提供器重设置defer属性为true:

protected $defer = true;

接下来你需要重写继承自基类Illuminate\Support\ServiceProvider的provides方法，并返回绑定了你的提供器，对应的IoC容器中类型的数组集合。例如，你的提供器在IoC容器注册了package.service 和 package.another-service两个类型，你的provides的方法看起来应该是这个样子：

public function provides()
{
    return array('package.service', 'package.another-service');
}

包约定

要使用包中的资源，例如配置或视图，需要用双冒号语法：

从包中载入视图

return View::make('package::view.name');

获取包的某个配置项

return Config::get('package::group.option');

注意: 如果你包中包含迁移，请为迁移名（migration name）添加包名作为前缀，以避免与其他包中的类名冲突。

开发流程

当开发一个包时，能够使用应用程序上文是相当有用的，这样将允许你很容易的解决视图模板的等问题。所以，我们开始，安装一个全新的Laravel框架，使用workbench命令创建包结构。

在使用workbench命令创建包后。你可以在workbench/[vendor]/[package]目录使用git init，并在workbench中直接git push！这将允许你在应用程序上下文中方便开发而不用为反复使用composer update命令苦扰。

当包存放在workbench目录时，你可能担心Composer如何知道自动加载包文件。当workbench目录存在，Laravel将智能扫描该目录，在应用程序开始时加载它们的Composer自动加载文件！

如果你需要重新生成包的自动加载文件，你可以使用php artisan dump-autoload命令，这个命令将会重新为您的整个项目生成自动加载文件，也包括你的工作台(workbenches)中的包

运行Artisan的自动加载命令

php artisan dump-autoload

包路由

在之前的Laravel版本中，handlers用来指定哪个URI包会响应。然而，在Laravel4中，一个包可以响应任意URI。要在包中加载路由文件，只需在服务提供器的boot方法include它。

在服务提供器中包含路由文件

public function boot()
{
    $this->package('vendor/package');

    include __DIR__.'/../../routes.php';
}

注意: 如果你的包中使用了控制器, 你需要确保正确配置了composer.json文件的auto-load字段.

包配置

访问包配置文件

有时创建的包可能会需要配置文件。这些配置文件应该和应用程序配置文件相同方法定义。并且，当使用 $this->package方法来注册服务提供器时，那么就可以使用“双冒号”语法来访问：

Config::get('package::file.option');

访问包单一配置文件

然而，如果你包仅有一个配置文件，你可以简单命名为config.php。当你这么做时，你可以直接访问该配置项，而不需要特别指明文件名： Config::get('package::option');

Registering A Resource Namespace Manually

手动注册资源的命名空间

有时候，你可能希望在$this->package特有方法之外注册包的资源，比如视图。通常只有在这些资源不在约定的位置的时候才应该这么做。如果需要手动注册资源，你可以使用View, Lang, 和 Config 中的addNamespace方法实现:

View::addNamespace('package', __DIR__.'/path/to/views');

一旦这个资源命名空间被注册，你就可以使用这个空间名，并使用"双冒号"语法去访问这个资源

return View::make('package::view.name');

View, Lang, 和 Config类中的addNamespace方法的参数都是一样的

级联配置文件

但其他开发者安装你的包时，他们也许需要覆盖一些配置项。然而，如果从包源代码中改变值，他们将会在下次使用Composer更新包时又被覆盖。替代方法是使用artisan命令config:publish：

php artisan config:publish vendor/package

当执行该命令，配置文件就会拷贝到app/config/packages/vendor/package，开发者就可以安全的更改配置项了。

注意: 开发者也可以为该包创建指定环境下的配置文件，替换某些配置项然后并放置在app/config/packages/vendor/package/environment.

包视图

如果在你的应用程序中使用某个包，你可能会定制这个包的视图。你可以很轻松的将这个包的视图文件导入到你自己的app/views目录，只需使用view:publish这个Artisan命令

php artisan view:publish vendor/package

这个命令会将包的视图文件迁移到app/views/packages目录，如果这个目录不存在，将会被创建。一旦这些视图文件被公开创建，你就可以按照你自己的喜好去修改他们，这些导出的视图会比包自己的视图文件优先载入。

包迁移

为工作台(Workbench)的包创建迁移

你可以很容易在包中创建和运行迁移。要为工作台里的包创建迁移，使用--bench选项：

php artisan migrate:make create_users_table --bench="vendor/package"

为工作台(Workbench)的包运行迁移

php artisan migrate --bench="vendor/package"

为已安装的包执行迁移

要为已经通过Composer安装在vendor目录下的包执行迁移，你可以直接使用--package：

php artisan migrate --package="vendor/package"

包Assets

将包Assets移动到Public

有些包可能含有assets，例如JavaScript，CSS，和图片。然而，我们无法链接到vendor或workbench目录里的assets，所以我们需要可以将这些assets移入应用程序的public目录。asset:publish命令可以实现：

php artisan asset:publish

php artisan asset:publish vendor/package

如果这个包仍在workbench中，那么请使用--bench指令:

php artisan asset:publish --bench="vendor/package"

这个命令将会把assets移入与“供应商”和“包名”相对应的public/packages目录下面。因此，包名为userscape/kudos的assets将会被移至public/packages/userscape/kudos。通过使用这个assets发布方法，可以让您安全的在包中的view内访问assets路径。

发布包

当你创建的包准备发布时，你应该将包提交到 Packagist 仓库。如果你的包只针对Laravel，最好在包的composer.json文件中添加laravel标签

还有，在发布的版本中添加tag，以便开发者能当请求你的包在他们composer.json文件中依赖稳定版本。如果稳定版本还没有好，考虑直接在Composer中使用branch-alias。

一旦你的包发布，放舒心，继续在由workbench创建的包中，结合应用程序上下文进行开发。对于在发布包后继续进行开发，这是相当便利的。

一些组织使用他们私有分支包为他们自己开发者。如果你对这感兴趣，查看Composer团队构建的Satis 文档。

译者：mpandar（马胜盼）