[best practice] creating-the-project.rst の原文を追加

Author: kseta

best_practices/creating-the-project.rst

@@ -0,0 +1,253 @@
+Creating the Project
+====================
+
+Installing Symfony
+------------------
+
+There is only one recommended way to install Symfony:
+
+.. best-practice::
+
+    Always use `Composer`_ to install Symfony.
+
+Composer is the dependency manager used by modern PHP applications. Adding or
+removing requirements for your project and updating the third-party libraries
+used by your code is a breeze thanks to Composer.
+
+Dependency Management with Composer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before installing Symfony, you need to make sure that you have Composer installed
+globally. Open your terminal (also called *command console*) and run the following
+command:
+
+.. code-block:: bash
+
+    $ composer --version
+    Composer version 1e27ff5e22df81e3cd0cd36e5fdd4a3c5a031f4a 2014-08-11 15:46:48
+
+You'll probably see a different version identifier. Never mind because Composer
+is updated on a continuous basis and its specific version doesn't matter.
+
+Installing Composer Globally
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In case you don't have Composer installed globally, execute the following two
+commands if you use Linux or Mac OS X (the second command will ask for your
+user password):
+
+.. code-block:: bash
+
+    $ curl -sS https://getcomposer.org/installer | php
+    $ sudo mv composer.phar /usr/local/bin/composer
+
+.. note::
+
+    Depending on your Linux distribution, you may need to execute ``su`` command
+    instead of ``sudo``.
+
+If you use a Windows system, download the executable installer from the
+`Composer download page`_ and follow the steps to install it.
+
+Creating the Blog Application
+-----------------------------
+
+Now that everything is correctly set up, you can create a new project based on
+Symfony. In your command console, browse to a directory where you have permission
+to create files and execute the following commands:
+
+.. code-block:: bash
+
+    $ cd projects/
+    $ composer create-project symfony/framework-standard-edition blog/
+
+This command will create a new directory called ``blog`` that will contain
+a fresh new project based on the most recent stable Symfony version available.
+
+Checking the Symfony Installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the installation is finished, enter the ``blog/`` directory and check that
+Symfony is correctly installed by executing the following command:
+
+.. code-block:: bash
+
+    $ cd blog/
+    $ php app/console --version
+
+    Symfony version 2.6.* - app/dev/debug
+
+If you see the installed Symfony version, everything worked as expected. If not,
+you can execute the following *script* to check what does prevent your system
+from correctly executing Symfony applications:
+
+.. code-block:: bash
+
+    $ php app/check.php
+
+Depending on your system, you can see up to two different lists when executing the
+`check.php` script. The first one shows the mandatory requirements which your
+system must meet to execute Symfony applications. The second list shows the
+optional requirements suggested for an optimal execution of Symfony applications:
+
+.. code-block:: bash
+
+    Symfony2 Requirements Checker
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    > PHP is using the following php.ini file:
+      /usr/local/zend/etc/php.ini
+
+    > Checking Symfony requirements:
+      .....E.........................W.....
+
+    [ERROR]
+    Your system is not ready to run Symfony2 projects
+
+    Fix the following mandatory requirements
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+     * date.timezone setting must be set
+       > Set the "date.timezone" setting in php.ini* (like Europe/Paris).
+
+    Optional recommendations to improve your setup
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+     * short_open_tag should be disabled in php.ini
+       > Set short_open_tag to off in php.ini*.
+
+
+.. tip::
+
+    Symfony releases are digitally signed for security reasons. If you want to
+    verify the integrity of your Symfony installation, take a look at the
+    `public checksums repository`_ and follow `these steps`_ to verify the
+    signatures.
+
+Structuring the Application
+---------------------------
+
+After creating the application, enter the ``blog/`` directory and you'll see a
+number of files and directories generated automatically:
+
+.. code-block:: text
+
+    blog/
+    ├─ app/
+    │  ├─ console
+    │  ├─ cache/
+    │  ├─ config/
+    │  ├─ logs/
+    │  └─ Resources/
+    ├─ src/
+    │  └─ AppBundle/
+    ├─ vendor/
+    └─ web/
+
+This file and directory hierarchy is the convention proposed by Symfony to
+structure your applications. The recommended purpose of each directory is the
+following:
+
+* ``app/cache/``, stores all the cache files generated by the application;
+* ``app/config/``, stores all the configuration defined for any environment;
+* ``app/logs/``, stores all the log files generated by the application;
+* ``app/Resources/``, stores all the templates and the translation files for the
+  application;
+* ``src/AppBundle/``, stores the Symfony specific code (controllers and routes),
+  your domain code (e.g. Doctrine classes) and all your business logic;
+* ``vendor/``, this is the directory where Composer installs the application's
+  dependencies and you should never modify any of its contents;
+* ``web/``, stores all the front controller files and all the web assets, such
+  as stylesheets, JavaScript files and images.
+
+Application Bundles
+~~~~~~~~~~~~~~~~~~~
+
+When Symfony 2.0 was released, most developers naturally adopted the symfony
+1.x way of dividing applications into logical modules. That's why many Symfony
+apps use bundles to divide their code into logical features: ``UserBundle``,
+``ProductBundle``, ``InvoiceBundle``, etc.
+
+But a bundle is *meant* to be something that can be reused as a stand-alone
+piece of software. If ``UserBundle`` cannot be used *"as is"* in other Symfony
+apps, then it shouldn't be its own bundle. Moreover ``InvoiceBundle`` depends
+on ``ProductBundle``, then there's no advantage to having two separate bundles.
+
+.. best-practice::
+
+    Create only one bundle called ``AppBundle`` for your application logic
+
+Implementing a single ``AppBundle`` bundle in your projects will make your code
+more concise and easier to understand. Starting in Symfony 2.6, the official
+Symfony documentation uses the ``AppBundle`` name.
+
+.. note::
+
+    There is no need to prefix the ``AppBundle`` with your own vendor (e.g.
+    ``AcmeAppBundle``), because this application bundle is never going to be
+    shared.
+
+All in all, this is the typical directory structure of a Symfony application
+that follows these best practices:
+
+.. code-block:: text
+
+    blog/
+    ├─ app/
+    │  ├─ console
+    │  ├─ cache/
+    │  ├─ config/
+    │  ├─ logs/
+    │  └─ Resources/
+    ├─ src/
+    │  └─ AppBundle/
+    ├─ vendor/
+    └─ web/
+       ├─ app.php
+       └─ app_dev.php
+
+.. tip::
+
+    If you are using Symfony 2.6 or a newer version, the ``AppBundle`` bundle
+    is already generated for you. If you are using an older Symfony version,
+    you can generate it by hand executing this command:
+
+    .. code-block:: bash
+
+        $ php app/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction
+
+Extending the Directory Structure
+---------------------------------
+
+If your project or infrastructure requires some changes to the default directory
+structure of Symfony, you can `override the location of the main directories`_:
+``cache/``, ``logs/`` and ``web/``.
+
+In addition, Symfony3 will use a slightly different directory structure when
+it's released:
+
+.. code-block:: text
+
+    blog-symfony3/
+    ├─ app/
+    │  ├─ config/
+    │  └─ Resources/
+    ├─ bin/
+    │  └─ console
+    ├─ src/
+    ├─ var/
+    │  ├─ cache/
+    │  └─ logs/
+    ├─ vendor/
+    └─ web/
+
+The changes are pretty superficial, but for now, we recommend that you use
+the Symfony2 directory structure.
+
+.. _`Composer`: https://getcomposer.org/
+.. _`Get Started`: https://getcomposer.org/doc/00-intro.md
+.. _`Composer download page`: https://getcomposer.org/download/
+.. _`override the location of the main directories`: http://symfony.com/doc/current/cookbook/configuration/override_dir_structure.html
+.. _`public checksums repository`: https://github.com/sensiolabs/checksums
+.. _`these steps`: http://fabien.potencier.org/article/73/signing-project-releases
+