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

Author: 77web

best_practices/business-logic.rst

@@ -0,0 +1,335 @@
+アプリケーションのビジネスロジックを整理する
+==============================================
+
+コンピュータのソフトウェアの世界では、データがどのように作られ、表示され、保存され、変更されるかを決める
+現実世界のビジネスルールを実装したプログラムを  **ビジネスロジック** あるいはドメインロジックと呼びます。
+（ `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::
+
+    アプリケーションのサービス名は可能な限り短くしましょう。一単語になるのが理想的です。
+
+これで ``AdminController`` のようなどんなコントローラーからでも slugger を利用できるようになりました。
+
+.. code-block:: php
+
+    public function createAction(Request $request)
+    {
+        // ...
+
+        if ($form->isSubmitted() && $form->isValid()) {
+            $slug = $this->get('slugger')->slugify($post->getTitle()));
+            $post->setSlug($slug);
+
+            // ...
+        }
+    }
+
+サービス定義：YAML形式
+--------------------------
+
+前のセクションでは、 YAML がサービスを定義するのに使われていました。
+
+.. best-practice::
+
+    サービスを定義するときは YAML 形式を使いましょう。
+
+これには異論があるでしょうが、経験上、開発者の間では YAML と XML が半々で使われており、ほんの少し YAML
+のほうが好まれています。
+どちらの形式も機能は同じなので、どこまでも個人の好みの問題です。
+
+新人にもわかりやすく、シンプルな YAML をお勧めしますが、好きな形式を使って構いません。
+
+サービス定義：クラス名をパラメータにしない
+-------------------------------------------
+
+前の例で、サービスを定義するとき、クラス名をパラメータとして定義していないことにお気付きかもしれません。
+
+.. code-block:: yaml
+
+    # app/config/services.yml
+
+    # クラス名をパラメータにしてサービスを定義
+    parameters:
+        slugger.class: AppBundle\Utils\Slugger
+
+    services:
+        slugger:
+            class: "%slugger.class%"
+
+この使い方は煩雑で、アプリケーションのサービスには全く必要ありません。
+
+.. best-practice::
+
+    アプリケーションのサービスクラスをパラメータとして定義するのは止めましょう。    
+
+この使い方はサードパーティのバンドルから誤って取り入れられたものです。 Symfony がサービスコンテナ機能を
+実装したとき、開発者の中にはこのテクニックによってサービスを上書きできるようにした人もいました。
+しかし、クラス名を変更しただけでサービスを上書きするのは非常に稀なユースケースです。というのも、大抵の場合、
+新しいサービスには、上書きされるサービスとは違うコンストラクタ引数があるからです。
+
+永続化レイヤーを利用する
+-------------------------
+
+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