From 5b8ba09bfc30cf95f39a9edd510a77604984baa4 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Sat, 7 Apr 2012 18:46:58 +0200 Subject: [PATCH] Renamed phpdocumentor/template. to phpdocumentor/template- and limited line length to 80 characters --- doc/articles/custom-installers.md | 92 ++++++++++++++++++++++--------- 1 file changed, 65 insertions(+), 27 deletions(-) diff --git a/doc/articles/custom-installers.md b/doc/articles/custom-installers.md index 5bd1b2454..f308cc0c4 100644 --- a/doc/articles/custom-installers.md +++ b/doc/articles/custom-installers.md @@ -2,50 +2,69 @@ ## Synopsis -At times it may be necessary for a package to require additional actions during installation, such as installing packages outside of the default `vendor` library. +At times it may be necessary for a package to require additional actions during +installation, such as installing packages outside of the default `vendor` +library. -In these cases you could consider creating a Custom Installer to handle your specific logic. +In these cases you could consider creating a Custom Installer to handle your +specific logic. ## Calling a Custom Installer -Suppose that your project already has a Custom Installer for specific modules then invoking that installer is a matter of defining the correct [type][1] in your package file. +Suppose that your project already has a Custom Installer for specific modules +then invoking that installer is a matter of defining the correct [type][1] in +your package file. > _See the next chapter for an instruction how to create Custom Installers._ -Every Custom Installer defines which [type][1] string it will recognize. Once recognized it will completely override the default installer and only apply its own logic. +Every Custom Installer defines which [type][1] string it will recognize. Once +recognized it will completely override the default installer and only apply its +own logic. An example use-case would be: -> phpDocumentor features Templates that need to be installed outside of the default /vendor folder structure. As such they have chosen to adopt the `phpdocumentor-template` [type][1] and create a Custom Installer to send these templates to the correct folder. +> phpDocumentor features Templates that need to be installed outside of the +> default /vendor folder structure. As such they have chosen to adopt the +> `phpdocumentor-template` [type][1] and create a Custom Installer to send +> these templates to the correct folder. An example composer.json of such a template would be: { - "name": "phpdocumentor/template.responsive", + "name": "phpdocumentor/template-responsive", "type": "phpdocumentor-template", } -With the package definition shown in the example will any project that includes this package try to find an appropriate installer and use that to execute this [type][1]. +With the package definition shown in the example will any project that includes +this package try to find an appropriate installer and use that to execute this +[type][1]. -> **IMPORTANT**: the host project will not recognize the [type][1] if the installer's package is not included. Thus a composer.json consuming a template package will always need to _require_ the template's installer as well. +> **IMPORTANT**: the host project will not recognize the [type][1] if the +> installer's package is not included. Thus a composer.json consuming a template +> package will always need to _require_ the template's installer as well. ## Creating an Installer -A Custom Installer is a defined as a class that implements the [\Composer\Installer\InstallerInterface][3] and is contained in a Composer package that has the [type][1] `composer-installer`. +A Custom Installer is a defined as a class that implements the +[\Composer\Installer\InstallerInterface][3] and is contained in a Composer +package that has the [type][1] `composer-installer`. A basic Installer would thus compose of two files: 1. the package file: composer.json 2. The Installer class, i.e.: \Composer\Installer\MyInstaller.php -> **NOTE**: _The namespace does not need to be \Composer\Installer, it may be anything that you would want._ +> **NOTE**: _The namespace does not need to be \Composer\Installer, it may be +> anything that you would want._ ### composer.json -The package file is the same as any other package file but with the following requirements: +The package file is the same as any other package file but with the following +requirements: -1. the [type][1] attribute must be `composer-installer` -2. the [extra][2] attribute must contain an element `class` defining the class name of the installer (including namespace) +1. the [type][1] attribute must be `composer-installer`. +2. the [extra][2] attribute must contain an element `class` defining the + class name of the installer (including namespace). Example: @@ -61,21 +80,32 @@ Example: ### The Custom Installer class -The class that executes the custom installation should implement the [\Composer\Installer\InstallerInterface][3] (or extend another installer that implements that interface). +The class that executes the custom installation should implement the +[\Composer\Installer\InstallerInterface][3] (or extend another installer that +implements that interface). -The class may be placed in any location and have any name, as long as it matches the `extra.class` element in the package definition. -It will also define the [type][1] string as it will be recognized by packages that will use this installer in the `supports()` method. +The class may be placed in any location and have any name, as long as it +matches the `extra.class` element in the package definition. +It will also define the [type][1] string as it will be recognized by packages +that will use this installer in the `supports()` method. -> **NOTE**: _choose your [type][1] name carefully, it is recommended to follow the format: `vendor-type`_. For example: `phpdocumentor-template` +> **NOTE**: _choose your [type][1] name carefully, it is recommended to follow +> the format: `vendor-type`_. For example: `phpdocumentor-template`. -The InstallerInterface class defines the following methods (please see the source for the exact signature): +The InstallerInterface class defines the following methods (please see the +source for the exact signature): -* **supports()**, here you test whether the passed [type][1] matches the name that you declared for this installer (see the example). +* **supports()**, here you test whether the passed [type][1] matches the name + that you declared for this installer (see the example). * **isInstalled()**, determines whether a supported package is installed or not. -* **install()**, here you can determine the actions that need to be executed upon installation. -* **update()**, here you define the behavior that is required when Composer is invoked with the update argument. -* **uninstall()**, here you can determine the actions that need to be executed when the package needs to be removed. -* **getInstallPath()**, this method should return the location where the package is to be installed, _relative from the location of composer.json._ +* **install()**, here you can determine the actions that need to be executed + upon installation. +* **update()**, here you define the behavior that is required when Composer is + invoked with the update argument. +* **uninstall()**, here you can determine the actions that need to be executed + when the package needs to be removed. +* **getInstallPath()**, this method should return the location where the + package is to be installed, _relative from the location of composer.json._ Example: @@ -90,11 +120,15 @@ Example: */ public function getInstallPath(PackageInterface $package) { - if (substr($package->getPrettyName(), 0, 23) != 'phpdocumentor/template.') { + $prefix = substr($package->getPrettyName(), 0, 23); + if ('phpdocumentor/template-' != $prefix) { throw new \InvalidArgumentException( - 'Unable to install template, phpdocumentor templates should always start their package name with "phpdocumentor/template."' + 'Unable to install template, phpdocumentor templates ' + .'should always start their package name with ' + .'"phpdocumentor/template-"' ); } + return 'data/templates/'.substr($package->getPrettyName(), 23); } @@ -107,9 +141,13 @@ Example: } } -The example demonstrates that it is quite simple to extend the [\Composer\Installer\LibraryInstaller][4] class to strip a prefix (`phpdocumentor/template.`) and use the remaining part to assemble a completely different installation path. +The example demonstrates that it is quite simple to extend the +[\Composer\Installer\LibraryInstaller][4] class to strip a prefix +(`phpdocumentor/template-`) and use the remaining part to assemble a completely +different installation path. -> _Instead of installing to `/vendor` will any package installed using this Installer be put in the `/data/templates/` folder._ +> _Instead of installing to `/vendor` will any package installed using this +> Installer be put in the `/data/templates/` folder._ [1]: http://getcomposer.org/doc/04-schema.md#type [2]: http://getcomposer.org/doc/04-schema.md#extra