tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 12:05:37 +00:00
Code Issues Projects Releases Wiki Activity

Updated composer docs

Browse Source
This commit is contained in:
Ingo Schommer 2013-02-25 11:46:56 +01:00
parent 57952977c7
commit 567e39cd19
2 changed files with 100 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
docs/en/installation/composer.md
View File

@ -7,6 +7,7 @@
Composer is a package management tool for PHP that lets you install and upgrade SilverStripe and its modules. Although installing Composer is one extra step, it will give you much more flexibility than just downloading the file from silverstripe.org. This is our recommended way of downloading SilverStripe and managing your code.
For more information about Composer, visit [its website](http://getcomposer.org/).
We also have separate instructions for [installing modules with Composer](/topics/modules).
# Basic usage
@ -100,7 +101,7 @@ So, your deployment process, as it relates to Composer, should be as follows:
* Deploy your project code base, using the deployment tool of your choice.
* Run `composer install` on your production version.
# Setting up an environment for contributing to SilverStripe {#contributing}
# Dev Environments for Contributing Code {#contributing}
So you want to contribute to SilverStripe? Fantastic! You can do this with composer too.
You have to tell composer three things in order to be able to do this:
@ -243,3 +244,49 @@ Both the version and the alias are specified as Composer versions, not branch na
This is not the only way to set things up in Composer. For more information on this topic, read the ["Aliases" chapter of the Composer documentation](http://getcomposer.org/doc/articles/aliases.md).
## FAQ
### How do I convert an existing module to using Composer?
Simply decide on a [unique name and vendor prefix](https://packagist.org/about),
create a `composer.json`, and either commit it or send a pull request to the module author.
Look at existing modules like the ["blog" module](https://github.com/silverstripe/silverstripe-blog/blob/master/composer.json) for good examples on what this file should contain.
Then register the module on [packagist.org](http://packagist.org).
### What about themes?
Themes are technically just "modules" which are placed in the `themes/` subdirectory.
We denote a special type for them in the `composer.json` (`"type": "silverstripe-module"`),
which triggers their installation into the correct path.
### How do I convert an existing project to Composer?
The easiest way is to follow the [/installation/upgrading] instructions
and switch to a newer release. Alternatively, copy the `composer.json` file from
a newer release, and adjust the version settings in the "require" section to your needs.
You'll also need to update your webserver configuration
from there (`.htaccess` or `web.config` files), in order to prevent
web access to the composer-generated files.
### Do I need composer on my live server?
It depends on your deployment process. If you copy or rsync files to your live server,
the process stays the same. If the live server hosts a git repository checkout,
which is updated to push a newer version, you'll also need to run `composer install` afterwards.
We recommend looking into [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) for this purpose.
### Can I keep using Downloads, Subversion Externals or Git Submodules?
Yes and no. Composer comes with additional features such as
[autoloading](http://getcomposer.org/doc/01-basic-usage.md#autoloading)
or [scripts](http://getcomposer.org/doc/articles/scripts.md)
which some modules will start relying on.
Please check the module README for specific installation instructions.
### I don't want to get development versions of everything!
You don't have to, Composer is designed to work on the constraints you set.
You can declare the ["minimum-stability"](http://getcomposer.org/doc/04-schema.md#minimum-stability)
on your project as suitable, or even whitelist specific modules as tracking
a development branch while keeping others to their stable release.
Read up on [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) on how this all fits together.

85
docs/en/topics/modules.md
View File

@ -27,67 +27,82 @@ Because of the broad definition of modules, they can be created for a number of
from your mysite folder. "cms" is an example of this.
* **CMS Add-ons:** A module can define an extension to the CMS, usually by defining special page types with their own
templates and behaviour. "blog", "ecommerce", "forum", and "gallery" are examples of this.
* **Blog Widgets:** A module can provide 1 or more blog-widget classes. See [widgets](/topics/widgets) for more information.
* **Widgets:** Small pieces of functionality such as showing the latest Comments or Flickr Photos. Since SilverStripe 3.0, they have been moved into a standalone module at [github.com/silverstripe/silverstripe-widgets](https://github.com/silverstripe/silverstripe-widgets).
* **Developer Tools:** A module can provide a number of classes or resource files that do nothing by themselves, but
instead make it easier for developers to build other applications.
## Finding Modules
* [Official module list on silverstripe.org](http://silverstripe.org/modules)
* [Subversion repository on open.silverstripe.org](http://open.silverstripe.org/browser/modules)
* [Packagist.org "silverstripe" tag](https://packagist.org/search/?tags=silverstripe)
* [Github.com "silverstripe" search](https://github.com/search?q=silverstripe&ref=commandbar)
## Installation
Modules should exist in the root folder of your SilverStripe. The root folder being the one that contains the
*framework*, *cms* and other folders.
Modules should exist in the root folder of your SilverStripe installation
(the directory containing the *framework* and *cms* subdirectories).
The following article explains the generic installation of a module. Individual modules have their own requirements such
as creating folders or configuring API keys. For information about installing or configuring a specific module see the
modules *INSTALL* (or *README*) file. Modules should adhere to the [directory-structure](/topics/directory-structure)
modules *README* file. Modules should adhere to the [directory-structure](/topics/directory-structure)
guidelines.
### Download
### From a Composer Package
To install a module you need to download the tar.gz file from the [modules page](http://www.silverstripe.org/modules) and extract this tar.gz to the root folder mentioned
above.
Our preferred way to manage module dependencies is through the [Composer][http://getcomposer.org]
package manager. It enables you to install modules from specific versions, checking for
compatibilities between modules and even allowing to track development branches of them.
Note some times the folders extracted from the tar.gz contain the version number or some other folders. You need to make
sure the folder name is the correct name of the module.
After [installing Composer](/installation/composer) itself,
you can run a simple command to install a module.
Each module has a unique identifier, consisting of a vendor prefix and name.
For example, the popular "blog" module has the identifier `silverstripe/blog`,
and would be installed with the following command executed in the root folder:
### Subversion
composer require silverstripe/blog:*@stable
#### Option 1: Checkout
This will fetch the latest compatible stable version. Every time you run
`composer update` afterwards, Composer will check for a new stable version.
To lock down to a specific version, branch or commit, read up on
[Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file).
You can also add modules by editing the "require" section of the `composer.json` file.
cd ~/Sites/yourSilverStripeProject/
svn co http://svn.silverstripe.com/open/modules/modulename/trunk modulename/
To find modules and their identifiers, search for them on [packagist.org](http://packagist.org).
<div class="notice" markdown="1">
Older releases (<3.0.3, <2.4.9) don't come with a `composer.json` file in your root folder,
which is required for its operation. In this case, we recommend upgrading to a newer release.
</div>
Note: Some modules are stored in subfolders. If you want to use a module that is in a subfolder, such as widgets, put
an _ between the subfolder name and the module name, like this:
### From an Archive Download
cd /your/website/root
svn co http://svn.silverstripe.com/open/modules/widgets/twitter/trunk widgets_twitter
Alternatively, you can download the archive file from the
[modules page](http://www.silverstripe.org/modules)
and extract it to the root folder mentioned above.
Github also provides archive downloads which are generated automatically for every tag/version.
<div class="notice" markdown="1">
The main folder extracted from the archive
might contain the version number or additional "container" folders above the actual module
codebase. You need to make sure the folder name is the correct name of the module
(e.g. "blog/" rather than "silverstripe-blog/"). This folder should contain a `_config.php` file.
While the module might register and operate in other structures,
paths to static files such as CSS or JavaScript won't work.
</div>
<div class="warning" markdown="1">
Some modules might not work at all with this approach since they rely on the
Composer [autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading)
or post-install hooks, so we recommend using Composer.
</div>
#### Option 2: Add to svn:externals
### Git Submodules and Subversion Externals
cd ~/Sites/yourSilverStripeProject/
svn propedit svn:externals .
Git and Subversion provide their own facilities for managing dependent repositories.
This is essentially a variation of the "Archive Download" approach,
and comes with the same caveats.
## Related
In the editor add the following line (lines if you want multiple)
modulename/ http://svn.silverstripe.com/open/modules/modulename/trunk
Exit the editor and then run
svn up
**Useful Links:**
* [Modules](/topics/module-developement)
* [Modules Development](/topics/module-developement)
* [Module Release Process](/misc/module-release-process)