wip: [best practice] add business-logic.rst

Author: 77web

best_practices/business-logic.rst

@@ -0,0 +1,341 @@
+アプリケーションのビジネスロジックを整理する
+==============================================
+
+コンピュータのソフトウェアの世界では、データがどのように作られ、表示され、保存され、変更されるかを決める
+現実世界のビジネスルールを実装したプログラムを  **ビジネスロジック** あるいはドメインロジックと呼びます。
+（ `full definition`_ を読む）
+
+Symfony のアプリケーションでは、ビジネスロジックは、フレームワーク（例えばルーティングやコントローラの
+ような）に依存せず、自由に書くことができます。
+サービスとして使われる、ドメインのクラス・ Doctrine のエンティティ・通常の PHP のクラスは、ビジネスロジック
+の一例です。
+
+ほとんどのプロジェクトにおいて、開発者は全てを ``AppBundle`` に置くべきです。AppBundleの中では、ビジネス
+ロジックを整理するための、どんなディレクトリでも作ることができます。
+
+.. code-block:: text
+
+    symfoy2-project/
+    ├─ app/
+    ├─ src/
+    │  └─ AppBundle/
+    │     └─ Utils/
+    │        └─ MyClass.php
+    ├─ vendor/
+    └─ web/
+
+クラスをバンドルの外に置く
+--------------------------------------
+
+しかし、ビジネスロジックをバンドルの中に入れておく技術的な理由は何もありません。 ``src`` ディレクトリの
+下に好きな名前空間を定義して、クラスをそこに置くこともできます。
+
+.. code-block:: text
+
+    symfoy2-project/
+    ├─ app/
+    ├─ src/
+    │  ├─ Acme/
+    │  │   └─ Utils/
+    │  │      └─ MyClass.php
+    │  └─ AppBundle/
+    ├─ vendor/
+    └─ web/
+
+.. tip::
+
+    ``AppBundle`` を使うことをお勧めするのは簡単さのためです。バンドルの中に必要なものと
+    バンドルの外でも問題ないものがよく理解できている場合は、クラスを ``AppBundle`` の外に
+    置いても構いません。
+
+サービス：名付けと形式
+---------------------------
+
+ブログアプリケーションに、 "Hello World" のような投稿タイトルを "hello-world" のようなスラグに変換する
+ユーティリティが必要だとします。スラグは、投稿のURLの一部として使われます。
+
+新しい ``Slugger`` クラスを ``src/AppBundle/Utils/`` ディレクトリの配下に作り、下記のような ``slugify()``
+メソッドを実装してみましょう。
+
+.. code-block:: php
+
+    // src/AppBundle/Utils/Slugger.php
+    namespace AppBundle\Utils;
+
+    class Slugger
+    {
+        public function slugify($string)
+        {
+            return preg_replace(
+                '/[^a-z0-9]/', '-', strtolower(trim(strip_tags($string)))
+            );
+        }
+    }
+
+次に、このクラスのための新しいサービスを定義します。
+
+.. code-block:: yaml
+
+    # app/config/services.yml
+    services:
+        # サービス名は短くしましょう
+        slugger:
+            class: AppBundle\Utils\Slugger
+
+伝統的に、サービスの名前は、衝突を避けるためにクラス名とクラスの場所を組み合わせたものでした。
+そうすると、このサービスは ``app.utils.slugger`` と呼ばれる *はず* でした。しかし、短い名前を使うことで、
+コードの読みやすさと使いやすさは向上するでしょう。
+
+.. best-practice::
+
+    The name of your application's services should be as short as possible,
+    ideally just one simple word.
+
+Now you can use the custom slugger in any controller class, such as the
+``AdminController``:
+
+.. code-block:: php
+
+    public function createAction(Request $request)
+    {
+        // ...
+
+        if ($form->isSubmitted() && $form->isValid()) {
+            $slug = $this->get('slugger')->slugify($post->getTitle()));
+            $post->setSlug($slug);
+
+            // ...
+        }
+    }
+
+Service Format: YAML
+--------------------
+
+In the previous section, YAML was used to define the service.
+
+.. best-practice::
+
+    Use the YAML format to define your own services.
+
+This is controversial, and in our experience, YAML and XML usage is evenly
+distributed among developers, with a slight preference towards YAML.
+Both formats have the same performance, so this is ultimately a matter of
+personal taste.
+
+We recommend YAML because it's friendly to newcomers and concise. You can
+of course use whatever format you like.
+
+Service: No Class Parameter
+---------------------------
+
+You may have noticed that the previous service definition doesn't configure
+the class namespace as a parameter:
+
+.. code-block:: yaml
+
+    # app/config/services.yml
+
+    # service definition with class namespace as parameter
+    parameters:
+        slugger.class: AppBundle\Utils\Slugger
+
+    services:
+        slugger:
+            class: "%slugger.class%"
+
+This practice is cumbersome and completely unnecessary for your own services:
+
+.. best-practice::
+
+    Don't define parameters for the classes of your services.
+
+This practice was wrongly adopted from third-party bundles. When Symfony
+introduced its service container, some developers used this technique to easily
+allow overriding services. However, overriding a service by just changing its
+class name is a very rare use case because, frequently, the new service has
+different constructor arguments.
+
+Using a Persistence Layer
+-------------------------
+
+Symfony is an HTTP framework that only cares about generating an HTTP response
+for each HTTP request. That's why Symfony doesn't provide a way to talk to
+a persistence layer (e.g. database, external API). You can choose whatever
+library of strategy you want for this.
+
+In practice, many Symfony applications rely on the independent
+`Doctrine project`_ to define their model using entities and repositories.
+Just like with business logic, we recommend storing Doctrine entities in
+the ``AppBundle``
+
+The three entities defined by our sample blog application are a good example:
+
+.. code-block:: text
+
+    symfony2-project/
+    ├─ ...
+    └─ src/
+       └─ AppBundle/
+          └─ Entity/
+             ├─ Comment.php
+             ├─ Post.php
+             └─ User.php
+
+.. tip::
+
+    If you're more advanced, you can of course store them under your own
+    namespace in ``src/``.
+
+Doctrine Mapping Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Doctrine Entities are plain PHP objects that you store in some "database".
+Doctrine only knows about your entities through the mapping metadata configured
+for your model classes. Doctrine supports four metadata formats: YAML, XML,
+PHP and annotations.
+
+.. best-practice::
+
+    Use annotations to define the mapping information of the Doctrine entities.
+
+Annotations are by far the most convenient and agile way of setting up and
+looking for mapping information:
+
+.. code-block:: php
+
+    namespace AppBundle\Entity;
+
+    use Doctrine\ORM\Mapping as ORM;
+    use Doctrine\Common\Collections\ArrayCollection;
+
+    /**
+     * @ORM\Entity
+     */
+    class Post
+    {
+        const NUM_ITEMS = 10;
+
+        /**
+         * @ORM\Id
+         * @ORM\GeneratedValue
+         * @ORM\Column(type="integer")
+         */
+        private $id;
+
+        /**
+         * @ORM\Column(type="string")
+         */
+        private $title;
+
+        /**
+         * @ORM\Column(type="string")
+         */
+        private $slug;
+
+        /**
+         * @ORM\Column(type="text")
+         */
+        private $content;
+
+        /**
+         * @ORM\Column(type="string")
+         */
+        private $authorEmail;
+
+        /**
+         * @ORM\Column(type="datetime")
+         */
+        private $publishedAt;
+
+        /**
+         * @ORM\OneToMany(
+         *      targetEntity="Comment",
+         *      mappedBy="post",
+         *      orphanRemoval=true
+         * )
+         * @ORM\OrderBy({"publishedAt" = "ASC"})
+         */
+        private $comments;
+
+        public function __construct()
+        {
+            $this->publishedAt = new \DateTime();
+            $this->comments = new ArrayCollection();
+        }
+
+        // getters and setters ...
+    }
+
+All formats have the same performance, so this is once again ultimately a
+matter of taste.
+
+Data Fixtures
+~~~~~~~~~~~~~
+
+As fixtures support is not enabled by default in Symfony, you should execute
+the following command to install the Doctrine fixtures bundle:
+
+.. code-block:: bash
+
+    $ composer require "doctrine/doctrine-fixtures-bundle"
+
+Then, enable the bundle in ``AppKernel.php``, but only for the ``dev`` and
+``test`` environments:
+
+.. code-block:: php
+
+    use Symfony\Component\HttpKernel\Kernel;
+
+    class AppKernel extends Kernel
+    {
+        public function registerBundles()
+        {
+            $bundles = array(
+                // ...
+            );
+
+            if (in_array($this->getEnvironment(), array('dev', 'test'))) {
+                // ...
+                $bundles[] = new Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle(),
+            }
+
+            return $bundles;
+        }
+
+        // ...
+    }
+
+We recommend creating just *one* `fixture class`_ for simplicity, though
+you're welcome to have more if that class gets quite large.
+
+Assuming you have at least one fixtures class and that the database access
+is configured properly, you can load your fixtures by executing the following
+command:
+
+.. code-block:: bash
+
+    $ php app/console doctrine:fixtures:load
+
+    Careful, database will be purged. Do you want to continue Y/N ? Y
+      > purging database
+      > loading AppBundle\DataFixtures\ORM\LoadFixtures
+
+Coding Standards
+----------------
+
+The Symfony source code follows the `PSR-1`_ and `PSR-2`_ coding standards that
+were defined by the PHP community. You can learn more about
+`the Symfony Code Standards`_ and even use the `PHP-CS-Fixer`_, which is
+a command-line utility that can fix the coding standards of an entire codebase
+in a matter of seconds.
+
+.. _`full definition`: http://en.wikipedia.org/wiki/Business_logic
+.. _`Toran Proxy`: https://toranproxy.com/
+.. _`Composer`: https://getcomposer.org/
+.. _`MVC architecture`: http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
+.. _`Doctrine project`: http://www.doctrine-project.org/
+.. _`fixture class`: http://symfony.com/doc/master/bundles/DoctrineFixturesBundle/index.html#writing-simple-fixtures
+.. _`PSR-1`: http://www.php-fig.org/psr/psr-1/
+.. _`PSR-2`: http://www.php-fig.org/psr/psr-2/
+.. _`the Symfony Code Standards`: http://symfony.com/doc/current/contributing/code/standards.html
+.. _`PHP-CS-Fixer`: https://github.com/fabpot/PHP-CS-Fixer