├── .gitignore
├── .gush.yml
├── README.md
├── elcodi
    ├── 404.html
    ├── __init__.py
    ├── base.html
    ├── content.html
    ├── css
    │   ├── base.css
    │   ├── bootstrap-custom.min.css
    │   ├── elcodi.css
    │   ├── font-awesome-4.0.3.css
    │   └── highlight.css
    ├── fonts
    │   ├── fontawesome-webfont.eot
    │   ├── fontawesome-webfont.svg
    │   ├── fontawesome-webfont.ttf
    │   └── fontawesome-webfont.woff
    ├── img
    │   ├── elcodi.png
    │   ├── favicon.ico
    │   └── grid.png
    ├── js
    │   ├── base.js
    │   ├── bootstrap-3.0.3.min.js
    │   ├── highlight.pack.js
    │   └── jquery-1.10.2.min.js
    ├── license
    │   └── highlight.js
    │   │   └── LICENSE
    ├── nav-sub.html
    ├── nav.html
    └── toc.html
├── manuscript
    ├── Book.txt
    ├── book
    │   ├── cart-architecture.md
    │   ├── category-architecture.md
    │   ├── commands.md
    │   ├── coupon-architecture.md
    │   ├── dictionary.md
    │   ├── emails.md
    │   ├── events.md
    │   ├── features.md
    │   ├── images
    │   │   ├── category.png
    │   │   ├── homepage.png
    │   │   ├── login.png
    │   │   ├── model-cart-cartline.png
    │   │   ├── model-cart-component.png
    │   │   ├── model-category.png
    │   │   ├── model-order-orderline.png
    │   │   ├── model-product-component.png
    │   │   ├── product.png
    │   │   ├── register.png
    │   │   ├── top-bar.png
    │   │   └── variant.png
    │   ├── index.md
    │   ├── payments.md
    │   ├── philosophy.md
    │   ├── plugins.md
    │   ├── processes.md
    │   ├── product-architecture.md
    │   ├── pull-requests.md
    │   ├── roadmap.md
    │   ├── running-test-suite.md
    │   ├── shipping.md
    │   ├── standards.md
    │   ├── templates.md
    │   ├── translate-elcodi.md
    │   ├── vagrant-quick-start.md
    │   ├── what-is-elcodi.md
    │   └── why-elcodi.md
    ├── component
    │   ├── entity-translator.md
    │   ├── index.md
    │   ├── media.md
    │   ├── menu.md
    │   ├── metrics.md
    │   ├── sitemap.md
    │   ├── state-transition-machine.md
    │   └── template.md
    ├── cookbook
    │   ├── adapters
    │   │   ├── currency-rates-populator.md
    │   │   ├── image-resize.md
    │   │   ├── location-loader.md
    │   │   ├── location-populator.md
    │   │   ├── location-provider.md
    │   │   ├── metric-bucket.md
    │   │   └── related-purchasables-provider.md
    │   ├── deprecation
    │   │   └── deprecate-a-method.md
    │   ├── implementation
    │   │   ├── implement-a-collector.md
    │   │   ├── implement-a-controller-and-a-command.md
    │   │   ├── implement-a-factory.md
    │   │   ├── implement-a-form-type.md
    │   │   ├── implement-a-repository.md
    │   │   ├── implement-an-entity.md
    │   │   └── implement-an-event-listener.md
    │   ├── index.md
    │   ├── installation
    │   │   ├── install-a-plugin.md
    │   │   └── install-dependent-bundles.md
    │   ├── overwrite
    │   │   ├── overwrite-a-parameter.md
    │   │   ├── overwrite-a-service.md
    │   │   └── overwrite-an-entity.md
    │   ├── usage
    │   │   ├── elcodi-watermark.md
    │   │   └── referrer-domain.md
    │   └── workflow
    │   │   └── create-automatic-coupon.md
    ├── images
    │   ├── category.png
    │   ├── homepage.png
    │   ├── login.png
    │   ├── model-cart-cartline.png
    │   ├── model-cart-component.png
    │   ├── model-category.png
    │   ├── model-order-orderline.png
    │   ├── model-product-component.png
    │   ├── product.png
    │   ├── register.png
    │   ├── title_page.png
    │   ├── top-bar.png
    │   └── variant.png
    ├── index.md
    └── quick-start.md
├── mkdocs.yml
└── yuml.md


/.gitignore:
--------------------------------------------------------------------------------
1 | /site
2 | 


--------------------------------------------------------------------------------
/.gush.yml:
--------------------------------------------------------------------------------
1 | adapter: github
2 | issue_tracker: github
3 | base: master
4 | table-pr:
5 |     place_holder: ['Notes', ':+1: :older_man:']
6 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Elcodi Documentation
 2 | 
 3 | This documentation is rendered online at 
 4 | [http://elcodi.io/docs](http://elcodi.io/docs)
 5 | 
 6 | * [Quick Start](http://elcodi.io/docs/quick-start/)
 7 | * [The Book](http://elcodi.io/docs/book/index.html)
 8 | * [The Components](http://elcodi.io/docs/components/index.html)
 9 | * [The Cookbook](http://elcodi.io/docs/cookbook/index.html)
10 | 
11 | ### Support
12 | 
13 | * You can ask your questions to the community in 
14 | [Gitter](http://gitter.im/elcodi/elcodi) and we'll try to help you as much as
15 | possible
16 | * Look for some help on [Stackoverflow](http://stackoverflow.com)
17 | * Ping us on [Twitter](http://twitter.com/elcodi_dev)
18 | * As a last resort, look at [google](http://google.com)!


--------------------------------------------------------------------------------
/elcodi/404.html:
--------------------------------------------------------------------------------
 1 | {% extends "base.html" %}
 2 | 
 3 | {% block content %}
 4 | 
 5 |     <div class="row-fluid">
 6 |       <div id="main-content" class="span12">
 7 |         <h1 id="404-page-not-found" style="text-align: center">404</h1>
 8 |         <p style="text-align: center"><strong>Page not found</strong></p>
 9 |       </div>
10 |     </div>
11 | 
12 | {% endblock %}
13 | 


--------------------------------------------------------------------------------
/elcodi/__init__.py:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/elcodi/__init__.py


--------------------------------------------------------------------------------
/elcodi/base.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html lang="en">
  3 |     <head>
  4 |         <meta charset="utf-8">
  5 |         <meta http-equiv="X-UA-Compatible" content="IE=edge">
  6 |         <meta name="viewport" content="width=device-width, initial-scale=1.0">
  7 |         {% if page_description %}<meta name="description" content="{{ page_description }}">{% endif %}
  8 |         {% if site_author %}<meta name="author" content="{{ site_author }}">{% endif %}
  9 |         {% if canonical_url %}<link rel="canonical" href="{{ canonical_url }}">{% endif %}
 10 |         {% if favicon %}<link rel="shortcut icon" href="{{ base_url }}/{{ favicon }}">
 11 |         {% else %}<link rel="shortcut icon" href="{{ base_url }}/img/favicon.ico">{% endif %}
 12 | 
 13 |         <title>{% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}</title>
 14 | 
 15 |         <link href="{{ base_url }}/css/bootstrap-custom.min.css" rel="stylesheet">
 16 |         <link href="{{ base_url }}/css/font-awesome-4.0.3.css" rel="stylesheet">
 17 |         <link href="{{ base_url }}/css/base.css" rel="stylesheet">
 18 |         <link rel="stylesheet" href="{{ base_url }}/css/highlight.css">
 19 |         {%- for path in extra_css %}
 20 |         <link href="{{ path }}" rel="stylesheet">
 21 |         {%- endfor %}
 22 | 
 23 |         <link href="{{ base_url }}/css/elcodi.css" rel="stylesheet">
 24 | 
 25 |         <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
 26 |         <!--[if lt IE 9]>
 27 |             <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
 28 |             <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
 29 |         <![endif]-->
 30 | 
 31 |         {% if google_analytics %}
 32 |         <script>
 33 |             (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
 34 |             (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
 35 |             m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
 36 |             })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
 37 | 
 38 |             ga('create', '{{ google_analytics[0] }}', '{{ google_analytics[1] }}');
 39 |             ga('send', 'pageview');
 40 |         </script>
 41 |         {% endif %}
 42 |     </head>
 43 | 
 44 |     <body{% if current_page and current_page.is_homepage %} class="homepage"{% endif %}>
 45 | 
 46 |         {% include "nav.html" %}
 47 | 
 48 |         <div class="container">
 49 |             {% block content %}
 50 |                 <div class="col-md-3">{% include "toc.html" %}</div>
 51 |                 <div class="col-md-9" role="main">{% include "content.html" %}</div>
 52 |             {% endblock %}
 53 |         </div>
 54 | 
 55 |         <footer class="col-md-12">
 56 |             <hr>
 57 |             {% if copyright %}
 58 |                 <p>{{ copyright }}</p>
 59 |             {% endif %}
 60 |         </footer>
 61 | 
 62 |         <script src="{{ base_url }}/js/jquery-1.10.2.min.js"></script>
 63 |         <script src="{{ base_url }}/js/bootstrap-3.0.3.min.js"></script>
 64 |         <script src="{{ base_url }}/js/highlight.pack.js"></script>
 65 |         <script>var base_url = '{{ base_url }}';</script>
 66 |         <script data-main="{{ base_url }}/mkdocs/js/search.js" src="{{ base_url }}/mkdocs/js/require.js"></script>
 67 |         <script src="{{ base_url }}/js/base.js"></script>
 68 |         {%- for path in extra_javascript %}
 69 |         <script src="{{ path }}"></script>
 70 |         {%- endfor %}
 71 | 
 72 |         <div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="Search Modal" aria-hidden="true">
 73 |             <div class="modal-dialog">
 74 |                 <div class="modal-content">
 75 |                     <div class="modal-header">
 76 |                         <button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
 77 |                         <h4 class="modal-title" id="exampleModalLabel">Search</h4>
 78 |                     </div>
 79 |                     <div class="modal-body">
 80 |                         <p>
 81 |                             From here you can search these documents. Enter
 82 |                             your search terms below.
 83 |                         </p>
 84 |                         <form role="form">
 85 |                             <div class="form-group">
 86 |                                 <input type="text" class="form-control" placeholder="Search..." id="mkdocs-search-query">
 87 |                             </div>
 88 |                         </form>
 89 |                         <div id="mkdocs-search-results"></div>
 90 |                     </div>
 91 |                     <div class="modal-footer">
 92 |                     </div>
 93 |                 </div>
 94 |             </div>
 95 |         </div>
 96 | 
 97 |     </body>
 98 | </html>
 99 | {% if current_page and current_page.is_homepage %}
100 | <!--
101 | MkDocs version : {{ mkdocs_version }}
102 | Build Date UTC : {{ build_date_utc }}
103 | -->
104 | {% endif %}
105 | 


--------------------------------------------------------------------------------
/elcodi/content.html:
--------------------------------------------------------------------------------
 1 | {% if meta.source %}
 2 | <div class="source-links">
 3 | {% for filename in meta.source %}
 4 |     <span class="label label-primary">{{ filename }}</span>
 5 | {% endfor %}
 6 | </div>
 7 | {% endif %}
 8 | 
 9 | {{ content }}
10 | 


--------------------------------------------------------------------------------
/elcodi/css/base.css:
--------------------------------------------------------------------------------
  1 | body {
  2 |     padding-top: 70px;
  3 |     background: url(../img/grid.png) repeat-x;
  4 |     background-attachment: fixed;
  5 |     background-color: #f8f8f8;
  6 | }
  7 | 
  8 | body > div.container {
  9 |     min-height: 400px;
 10 | }
 11 | 
 12 | ul.nav li.main {
 13 |     font-weight: bold;
 14 | }
 15 | 
 16 | div.col-md-3 {
 17 |     padding-left: 0;
 18 | }
 19 | 
 20 | div.col-md-9 {
 21 |     padding-bottom: 100px;
 22 | }
 23 | 
 24 | div.source-links {
 25 |     float: right;
 26 | }
 27 | 
 28 | div.col-md-9 img {
 29 |     max-width: 100%;
 30 |     display: inline;
 31 |     padding: 4px;
 32 |     line-height: 1.428571429;
 33 |     background-color: #fff;
 34 |     border: 1px solid #ddd;
 35 |     border-radius: 4px;
 36 |     margin: 20px auto 30px auto;
 37 | }
 38 | 
 39 | h1, h2, h3 {
 40 |     color: #444;
 41 | }
 42 | 
 43 | h1[id]:before, h2[id]:before, h3[id]:before, h4[id]:before, h5[id]:before, h6[id]:before {
 44 |     content: "";
 45 |     display: block;
 46 |     margin-top: -75px;
 47 |     height: 75px;
 48 |     pointer-events: none;
 49 | }
 50 | 
 51 | h1 {
 52 |     font-weight: 400;
 53 |     font-size: 42px;
 54 | }
 55 | 
 56 | h2, h3, h4, h5, h6 {
 57 |     font-weight: 300;
 58 | }
 59 | 
 60 | hr {
 61 |     border-top: 1px solid #aaa;
 62 | }
 63 | 
 64 | pre, .rst-content tt {
 65 |     max-width: 100%;
 66 |     background: #fff;
 67 |     border: solid 1px #e1e4e5;
 68 |     color: #e74c3c;
 69 |     overflow-x: auto;
 70 | }
 71 | 
 72 | code.code-large, .rst-content tt.code-large {
 73 |     font-size: 90%;
 74 | }
 75 | 
 76 | code {
 77 |     padding: 2px 5px;
 78 |     color: #c7254e;
 79 |     background-color: #f9f2f4;
 80 |     font-size: 75%;
 81 | }
 82 | 
 83 | code, kbd, pre, samp  {
 84 |     font-family: monospace,serif;
 85 |     font-size: 12px !important;
 86 | }
 87 | 
 88 | footer {
 89 |     margin-top: 30px;
 90 |     margin-bottom: 10px;
 91 |     text-align: center;
 92 |     font-weight: 200;
 93 | }
 94 | 
 95 | .modal-dialog {
 96 |     margin-top: 60px;
 97 | }
 98 | 
 99 | /*
100 |  * Side navigation
101 |  *
102 |  * Scrollspy and affixed enhanced navigation to highlight sections and secondary
103 |  * sections of docs content.
104 |  */
105 | 
106 | /* By default it's not affixed in mobile views, so undo that */
107 | .bs-sidebar.affix {
108 |     position: static;
109 | }
110 | 
111 | .bs-sidebar.well {
112 |     padding: 0;
113 |     max-height: 90%;
114 |     overflow-y: auto;
115 | }
116 | 
117 | /* First level of nav */
118 | .bs-sidenav {
119 |     padding-top:    10px;
120 |     padding-bottom: 10px;
121 |     border-radius: 5px;
122 | }
123 | 
124 | /* All levels of nav */
125 | .bs-sidebar .nav > li > a {
126 |     display: block;
127 |     padding: 5px 20px;
128 |     z-index: 1;
129 | }
130 | .bs-sidebar .nav > li > a:hover,
131 | .bs-sidebar .nav > li > a:focus {
132 |     text-decoration: none;
133 |     border-right: 1px solid;
134 | }
135 | .bs-sidebar .nav > .active > a,
136 | .bs-sidebar .nav > .active:hover > a,
137 | .bs-sidebar .nav > .active:focus > a {
138 |     font-weight: bold;
139 |     background-color: transparent;
140 |     border-right: 1px solid;
141 | }
142 | 
143 | /* Nav: second level (shown on .active) */
144 | .bs-sidebar .nav .nav {
145 |     display: none; /* Hide by default, but at >768px, show it */
146 |     margin-bottom: 8px;
147 | }
148 | .bs-sidebar .nav .nav > li > a {
149 |     padding-top:    3px;
150 |     padding-bottom: 3px;
151 |     padding-left: 30px;
152 |     font-size: 90%;
153 | }
154 | 
155 | /* Show and affix the side nav when space allows it */
156 | @media (min-width: 992px) {
157 |     .bs-sidebar .nav > .active > ul {
158 |         display: block;
159 |     }
160 |     /* Widen the fixed sidebar */
161 |     .bs-sidebar.affix,
162 |     .bs-sidebar.affix-bottom {
163 |         width: 213px;
164 |     }
165 |     .bs-sidebar.affix {
166 |         position: fixed; /* Undo the static from mobile first approach */
167 |         top: 80px;
168 |     }
169 |     .bs-sidebar.affix-bottom {
170 |         position: absolute; /* Undo the static from mobile first approach */
171 |     }
172 |     .bs-sidebar.affix-bottom .bs-sidenav,
173 |     .bs-sidebar.affix .bs-sidenav {
174 |         margin-top: 0;
175 |         margin-bottom: 0;
176 |     }
177 | }
178 | @media (min-width: 1200px) {
179 |     /* Widen the fixed sidebar again */
180 |     .bs-sidebar.affix-bottom,
181 |     .bs-sidebar.affix {
182 |         width: 263px;
183 |     }
184 | }
185 | 
186 | .headerlink {
187 |     font-family: FontAwesome;
188 |     font-size: 14px;
189 |     display: none;
190 |     padding-left: .5em;
191 | }
192 | 
193 | h1:hover .headerlink, h2:hover .headerlink, h3:hover .headerlink, h4:hover .headerlink, h5:hover .headerlink, h6:hover .headerlink{
194 |     display:inline-block;
195 | }
196 | 
197 | 
198 | 
199 | .admonition {
200 |     padding: 15px;
201 |     margin-bottom: 20px;
202 |     border: 1px solid transparent;
203 |     border-radius: 4px;
204 |     text-align: left;
205 | }
206 | 
207 | .admonition.note {
208 |     color: #3a87ad;
209 |     background-color: #d9edf7;
210 |     border-color: #bce8f1;
211 | }
212 | 
213 | .admonition.warning {
214 |     color: #c09853;
215 |     background-color: #fcf8e3;
216 |     border-color: #fbeed5;
217 | }
218 | 
219 | .admonition.danger {
220 |     color: #b94a48;
221 |     background-color: #f2dede;
222 |     border-color: #eed3d7;
223 | }
224 | 
225 | .admonition-title {
226 |     font-weight: bold;
227 |     text-align: left;
228 | }
229 | 
230 | 
231 | .dropdown-submenu {
232 |     position: relative;
233 | }
234 | 
235 | .dropdown-submenu>.dropdown-menu {
236 |     top: 0;
237 |     left: 100%;
238 |     margin-top: -6px;
239 |     margin-left: -1px;
240 |     -webkit-border-radius: 0 6px 6px 6px;
241 |     -moz-border-radius: 0 6px 6px;
242 |     border-radius: 0 6px 6px 6px;
243 | }
244 | 
245 | .dropdown-submenu:hover>.dropdown-menu {
246 |     display: block;
247 | }
248 | 
249 | .dropdown-submenu>a:after {
250 |     display: block;
251 |     content: " ";
252 |     float: right;
253 |     width: 0;
254 |     height: 0;
255 |     border-color: transparent;
256 |     border-style: solid;
257 |     border-width: 5px 0 5px 5px;
258 |     border-left-color: #ccc;
259 |     margin-top: 5px;
260 |     margin-right: -10px;
261 | }
262 | 
263 | .dropdown-submenu:hover>a:after {
264 |     border-left-color: #fff;
265 | }
266 | 
267 | .dropdown-submenu.pull-left {
268 |     float: none;
269 | }
270 | 
271 | .dropdown-submenu.pull-left>.dropdown-menu {
272 |     left: -100%;
273 |     margin-left: 10px;
274 |     -webkit-border-radius: 6px 0 6px 6px;
275 |     -moz-border-radius: 6px 0 6px 6px;
276 |     border-radius: 6px 0 6px 6px;
277 | }
278 | 


--------------------------------------------------------------------------------
/elcodi/css/elcodi.css:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Elcodi documentation theme
 3 |  *
 4 |  * @author Mickaël Andrieu <andrieu.travail@gmail.com>
 5 |  */
 6 | 
 7 | /**
 8 |  * Global rules
 9 |  */
10 | h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 {
11 |   font-family: "Open Sans",sans-serif !important;
12 | }
13 | 
14 | body a {
15 |     color: #3cc8c0;
16 | }
17 | 
18 | body a:focus, body a:hover{
19 |     color: #3cc8c0;
20 |     text-decoration: underline;
21 | }
22 | 
23 | /**
24 | * Header top bar
25 | */
26 | .navbar-default, .navbar {
27 |     background-color: #3cc8c0 !important;
28 |     color: #fff;
29 | }
30 | 
31 | .navbar-default .navbar-brand {
32 |   color: #fff;
33 | }
34 | 
35 | .navbar-default .navbar-brand:hover, .navbar-default .navbar-brand:focus {
36 |   color:#404040;
37 |   background-color: transparent;
38 | }
39 | 
40 | .navbar-default .navbar-nav>li>a:hover, .navbar-default .navbar-nav>li>a:focus {
41 |   color: #404040;
42 |   background-color: transparent;
43 | }
44 | 
45 | .navbar-default .navbar-nav>.active>a, .navbar-default .navbar-nav>.active>a:hover, .navbar-default .navbar-nav>.active>a:focus {
46 |     color: #fff;
47 |     background-color: transparent;
48 | }
49 | 
50 | .navbar-default .navbar-nav>li>a {
51 |     color: #fff;
52 | }
53 | 
54 | .navbar-default .navbar-nav>.disabled>a, .navbar-default .navbar-nav>.disabled>a:hover, .navbar-default .navbar-nav>.disabled>a:focus {
55 |   color: rgb(114, 114, 114);
56 |   background-color: transparent;
57 | }
58 | 
59 | .navbar-default .navbar-nav>.open>a, .navbar-default .navbar-nav>.open>a:hover, .navbar-default .navbar-nav>.open>a:focus {
60 |   color: rgb(114, 114, 114);
61 |   background-color: #fff;
62 | }
63 | 
64 | /**
65 |  * Table of content
66 |  */
67 | .bs-sidebar .nav > .active > a, .bs-sidebar .nav > .active:hover > a, .bs-sidebar .nav > .active:focus > a {
68 |   color: ;
69 | }
70 | 
71 | /**
72 |  * Tablet / smartphone rendering
73 |  */
74 | @media (max-width: 767px){
75 |   .navbar-default .navbar-nav .open .dropdown-menu>li>a {
76 |     color: #fff;
77 |   }
78 | }
79 | 


--------------------------------------------------------------------------------
/elcodi/css/highlight.css:
--------------------------------------------------------------------------------
  1 | /*
  2 | This is the GitHub theme for highlight.js
  3 | 
  4 | github.com style (c) Vasily Polovnyov <vast@whiteants.net>
  5 | 
  6 | */
  7 | 
  8 | .hljs {
  9 |   display: block;
 10 |   overflow-x: auto;
 11 |   padding: 0.5em;
 12 |   color: #333;
 13 |   -webkit-text-size-adjust: none;
 14 | }
 15 | 
 16 | .hljs-comment,
 17 | .diff .hljs-header,
 18 | .hljs-javadoc {
 19 |   color: #998;
 20 |   font-style: italic;
 21 | }
 22 | 
 23 | .hljs-keyword,
 24 | .css .rule .hljs-keyword,
 25 | .hljs-winutils,
 26 | .nginx .hljs-title,
 27 | .hljs-subst,
 28 | .hljs-request,
 29 | .hljs-status {
 30 |   color: #333;
 31 |   font-weight: bold;
 32 | }
 33 | 
 34 | .hljs-number,
 35 | .hljs-hexcolor,
 36 | .ruby .hljs-constant {
 37 |   color: #008080;
 38 | }
 39 | 
 40 | .hljs-string,
 41 | .hljs-tag .hljs-value,
 42 | .hljs-phpdoc,
 43 | .hljs-dartdoc,
 44 | .tex .hljs-formula {
 45 |   color: #d14;
 46 | }
 47 | 
 48 | .hljs-title,
 49 | .hljs-id,
 50 | .scss .hljs-preprocessor {
 51 |   color: #900;
 52 |   font-weight: bold;
 53 | }
 54 | 
 55 | .hljs-list .hljs-keyword,
 56 | .hljs-subst {
 57 |   font-weight: normal;
 58 | }
 59 | 
 60 | .hljs-class .hljs-title,
 61 | .hljs-type,
 62 | .vhdl .hljs-literal,
 63 | .tex .hljs-command {
 64 |   color: #458;
 65 |   font-weight: bold;
 66 | }
 67 | 
 68 | .hljs-tag,
 69 | .hljs-tag .hljs-title,
 70 | .hljs-rule .hljs-property,
 71 | .django .hljs-tag .hljs-keyword {
 72 |   color: #000080;
 73 |   font-weight: normal;
 74 | }
 75 | 
 76 | .hljs-attribute,
 77 | .hljs-variable,
 78 | .lisp .hljs-body,
 79 | .hljs-name {
 80 |   color: #008080;
 81 | }
 82 | 
 83 | .hljs-regexp {
 84 |   color: #009926;
 85 | }
 86 | 
 87 | .hljs-symbol,
 88 | .ruby .hljs-symbol .hljs-string,
 89 | .lisp .hljs-keyword,
 90 | .clojure .hljs-keyword,
 91 | .scheme .hljs-keyword,
 92 | .tex .hljs-special,
 93 | .hljs-prompt {
 94 |   color: #990073;
 95 | }
 96 | 
 97 | .hljs-built_in {
 98 |   color: #0086b3;
 99 | }
100 | 
101 | .hljs-preprocessor,
102 | .hljs-pragma,
103 | .hljs-pi,
104 | .hljs-doctype,
105 | .hljs-shebang,
106 | .hljs-cdata {
107 |   color: #999;
108 |   font-weight: bold;
109 | }
110 | 
111 | .hljs-deletion {
112 |   background: #fdd;
113 | }
114 | 
115 | .hljs-addition {
116 |   background: #dfd;
117 | }
118 | 
119 | .diff .hljs-change {
120 |   background: #0086b3;
121 | }
122 | 
123 | .hljs-chunk {
124 |   color: #aaa;
125 | }
126 | 


--------------------------------------------------------------------------------
/elcodi/fonts/fontawesome-webfont.eot:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/elcodi/fonts/fontawesome-webfont.eot


--------------------------------------------------------------------------------
/elcodi/fonts/fontawesome-webfont.ttf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/elcodi/fonts/fontawesome-webfont.ttf


--------------------------------------------------------------------------------
/elcodi/fonts/fontawesome-webfont.woff:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/elcodi/fonts/fontawesome-webfont.woff


--------------------------------------------------------------------------------
/elcodi/img/elcodi.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/elcodi/img/elcodi.png


--------------------------------------------------------------------------------
/elcodi/img/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/elcodi/img/favicon.ico


--------------------------------------------------------------------------------
/elcodi/img/grid.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/elcodi/img/grid.png


--------------------------------------------------------------------------------
/elcodi/js/base.js:
--------------------------------------------------------------------------------
 1 | function getSearchTerm()
 2 | {
 3 |     var sPageURL = window.location.search.substring(1);
 4 |     var sURLVariables = sPageURL.split('&');
 5 |     for (var i = 0; i < sURLVariables.length; i++)
 6 |     {
 7 |         var sParameterName = sURLVariables[i].split('=');
 8 |         if (sParameterName[0] == 'q')
 9 |         {
10 |             return sParameterName[1];
11 |         }
12 |     }
13 | }
14 | 
15 | $(document).ready(function() {
16 | 
17 |     var search_term = getSearchTerm(),
18 |         $search_modal = $('#mkdocs_search_modal');
19 | 
20 |     if(search_term){
21 |         $search_modal.modal();
22 |     }
23 | 
24 |     // make sure search input gets autofocus everytime modal opens.
25 |     $search_modal.on('shown.bs.modal', function () {
26 |         $search_modal.find('#mkdocs-search-query').focus();
27 |     });
28 | 
29 |     // Highlight.js
30 |     hljs.initHighlightingOnLoad();
31 |     $('table').addClass('table table-striped table-hover');
32 | });
33 | 
34 | 
35 | $('body').scrollspy({
36 |     target: '.bs-sidebar',
37 | });
38 | 
39 | /* Prevent disabled links from causing a page reload */
40 | $("li.disabled a").click(function() {
41 |     event.preventDefault();
42 | });
43 | 


--------------------------------------------------------------------------------
/elcodi/license/highlight.js/LICENSE:
--------------------------------------------------------------------------------
 1 | Copyright (c) 2006, Ivan Sagalaev
 2 | All rights reserved.
 3 | Redistribution and use in source and binary forms, with or without
 4 | modification, are permitted provided that the following conditions are met:
 5 | 
 6 |     * Redistributions of source code must retain the above copyright
 7 |       notice, this list of conditions and the following disclaimer.
 8 |     * Redistributions in binary form must reproduce the above copyright
 9 |       notice, this list of conditions and the following disclaimer in the
10 |       documentation and/or other materials provided with the distribution.
11 |     * Neither the name of highlight.js nor the names of its contributors 
12 |       may be used to endorse or promote products derived from this software 
13 |       without specific prior written permission.
14 | 
15 | THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
16 | EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18 | DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
19 | DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
22 | ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 | 


--------------------------------------------------------------------------------
/elcodi/nav-sub.html:
--------------------------------------------------------------------------------
 1 | {% if not nav_item.children %}
 2 | <li {% if nav_item.active %}class="active"{% endif %}>
 3 |     <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
 4 | </li>
 5 | {% else %}
 6 |   <li class="dropdown-submenu">
 7 |     <a tabindex="-1" href="">{{ nav_item.title }}</a>
 8 |     <ul class="dropdown-menu">
 9 |         {% for nav_item in nav_item.children %}
10 |             {% include "nav-sub.html" %}
11 |         {% endfor %}
12 |     </ul>
13 |   </li>
14 | {% endif %}
15 | 


--------------------------------------------------------------------------------
/elcodi/nav.html:
--------------------------------------------------------------------------------
 1 | <div class="navbar navbar-default navbar-fixed-top" role="navigation">
 2 |     <div class="container">
 3 | 
 4 |         <!-- Collapsed navigation -->
 5 |         <div class="navbar-header">
 6 |             {% if include_nav or include_next_prev or repo_url %}
 7 |             <!-- Expander button -->
 8 |             <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
 9 |                 <span class="sr-only">Toggle navigation</span>
10 |                 <span class="icon-bar"></span>
11 |                 <span class="icon-bar"></span>
12 |                 <span class="icon-bar"></span>
13 |             </button>
14 |             {% endif %}
15 | 
16 |             <!-- Main title -->
17 |             <a class="navbar-brand" href="{{ homepage_url }}"><img src="{{ base_url }}/img/elcodi.png" height="30" /></a>
18 |         </div>
19 | 
20 |         <!-- Expanded navigation -->
21 |         <div class="navbar-collapse collapse">
22 |             {% if include_nav %}
23 |                 <!-- Main navigation -->
24 |                 <ul class="nav navbar-nav">
25 |                 {% for nav_item in nav %}
26 |                 {% if nav_item.title == 'Home' %}
27 |                 {% else %}
28 |                     {% if nav_item.children %}
29 |                         <li class="dropdown{% if nav_item.active %} active{% endif %}">
30 |                             <a href="#" class="dropdown-toggle" data-toggle="dropdown">{{ nav_item.title }} <b class="caret"></b></a>
31 |                             <ul class="dropdown-menu">
32 |                             {% for nav_item in nav_item.children %}
33 |                                 {% include "nav-sub.html" %}
34 |                             {% endfor %}
35 |                             </ul>
36 |                         </li>
37 |                     {% else %}
38 |                         <li {% if nav_item.active %}class="active"{% endif %}>
39 |                             <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
40 |                         </li>
41 |                     {% endif %}
42 |                 {% endif %}
43 |                 {% endfor %}
44 |                 </ul>
45 |             {% endif %}
46 | 
47 |             <ul class="nav navbar-nav navbar-right">
48 |                 <li>
49 |                     <a href="#" data-toggle="modal" data-target="#mkdocs_search_modal">
50 |                         <i class="fa fa-search"></i> Search
51 |                     </a>
52 |                 </li>
53 |                 {% if include_next_prev %}
54 |                     <li {% if not previous_page %}class="disabled"{% endif %}>
55 |                         <a rel="next" {% if previous_page %}href="{{ previous_page.url }}"{% endif %}>
56 |                             <i class="fa fa-arrow-left"></i> Previous
57 |                         </a>
58 |                     </li>
59 |                     <li {% if not next_page %}class="disabled"{% endif %}>
60 |                         <a rel="prev" {% if next_page %}href="{{ next_page.url }}"{% endif %}>
61 |                             Next <i class="fa fa-arrow-right"></i>
62 |                         </a>
63 |                     </li>
64 |                 {% endif %}
65 |                 {% if repo_url %}
66 |                     <li>
67 |                         <a href="{{ repo_url }}">
68 |                             {% if repo_name == 'GitHub' %}
69 |                                 <i class="fa fa-github"></i>
70 |                             {% elif repo_name == 'Bitbucket' %}
71 |                                 <i class="fa fa-bitbucket"></i>
72 |                             {% endif %}
73 |                             {{ repo_name }}
74 |                         </a>
75 |                     </li>
76 |                 {% endif %}
77 |             </ul>
78 |         </div>
79 |     </div>
80 | </div>
81 | 


--------------------------------------------------------------------------------
/elcodi/toc.html:
--------------------------------------------------------------------------------
 1 | <div class="bs-sidebar hidden-print affix well" role="complementary">
 2 |     <ul class="nav bs-sidenav">
 3 |     {% for toc_item in toc %}
 4 |         <li class="main {% if toc_item.active %}active{% endif %}"><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
 5 |         {% for toc_item in toc_item.children %}
 6 |             <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
 7 |         {% endfor %}
 8 |     {% endfor %}
 9 |     </ul>
10 | </div>
11 | 


--------------------------------------------------------------------------------
/manuscript/Book.txt:
--------------------------------------------------------------------------------
 1 | quick-start.md
 2 | book/index.md
 3 | book/cart-architecture.md
 4 | book/category-architecture.md
 5 | book/commands.md
 6 | book/coupon-architecture.md
 7 | book/dictionary.md
 8 | book/emails.md
 9 | book/events.md
10 | book/features.md
11 | book/payments.md
12 | book/philosophy.md
13 | book/plugins.md
14 | book/processes.md
15 | book/product-architecture.md
16 | book/pull-requests.md
17 | book/roadmap.md
18 | book/running-test-suite.md
19 | book/shipping.md
20 | book/standards.md
21 | book/templates.md
22 | book/translate-elcodi.md
23 | book/vagrant-quick-start.md
24 | book/what-is-elcodi.md
25 | book/why-elcodi.md
26 | component/index.md
27 | component/entity-translator.md
28 | component/media.md
29 | component/menu.md
30 | component/metrics.md
31 | component/sitemap.md
32 | component/state-transition-machine.md
33 | component/template.md
34 | cookbook/index.md
35 | cookbook/adapters/currency-rates-populator.md
36 | cookbook/adapters/image-resize.md
37 | cookbook/adapters/location-loader.md
38 | cookbook/adapters/location-populator.md
39 | cookbook/adapters/location-provider.md
40 | cookbook/adapters/metric-bucket.md
41 | cookbook/adapters/related-purchasables-provider.md
42 | cookbook/deprecation/deprecate-a-method.md
43 | cookbook/implementation/implement-a-collector.md
44 | cookbook/implementation/implement-a-controller-and-a-command.md
45 | cookbook/implementation/implement-a-factory.md
46 | cookbook/implementation/implement-a-form-type.md
47 | cookbook/implementation/implement-a-repository.md
48 | cookbook/implementation/implement-an-entity.md
49 | cookbook/implementation/implement-an-event-listener.md
50 | cookbook/installation/install-a-plugin.md
51 | cookbook/installation/install-dependent-bundles.md
52 | cookbook/overwrite/overwrite-a-parameter.md
53 | cookbook/overwrite/overwrite-a-service.md
54 | cookbook/overwrite/overwrite-an-entity.md
55 | cookbook/usage/elcodi-watermark.md
56 | cookbook/usage/referrer-domain.md
57 | cookbook/workflow/create-automatic-coupon.md
58 | 


--------------------------------------------------------------------------------
/manuscript/book/category-architecture.md:
--------------------------------------------------------------------------------
 1 | # Category Architecture
 2 | 
 3 | Elcodi brings you a small and simple category structure. Small and simple
 4 | doesn't mean bad and useless, but with sufficient quality to be useful and 
 5 | scalable for any E-commerce.
 6 | 
 7 | ![Category model](images/model-category.png)
 8 | 
 9 | ## Category tree
10 | 
11 | The main service of the component, and given that you have your categories built
12 | properly, is the service Category Tree. This service is only intended to create
13 | a basic structure of categories, ready to be saved in a plain way.
14 | 
15 | Imagine all steps in each Request without using this service.
16 | 
17 | * I want all categories
18 | * I need to get them all from Database using Doctrine
19 | * I need to sort them
20 | * I need to filter them
21 | * I need to organize them using the proper hierarchy
22 | 
23 | While there are no changes in your database, these bunch of actions produce the
24 | same result, so why we do it once and again? That's senseless.
25 | 
26 | This service will do this action only once and will save it in your cache
27 | system in a very reduced and simplified way. Of course the service will not save
28 | entities in cache but an array.
29 | 
30 | After that, each request will only require that structure saved in cache,
31 | reducing this way the resources spend by the system.
32 | 
33 | ## Flushing
34 | 
35 | As soon as your model changes, then you must flush your cache layer. At the
36 | moment this happens only when category or product table changes.
37 | 
38 | * Of course, if category changes, then the cached item should be flushed in 
39 | order to be rebuilt again.
40 | * Because some categories may not appear because of no products are attached to
41 | it, if the table products changes then the cached tree should be flushed as
42 | well. There is a flag that allow categories to appear even if they don't have
43 | products, so tree will be flushed only when this flag is disabled.
44 | 
45 | ## Overwrite the service
46 | 
47 | Each project may add their own login about how categories should be stored.
48 | That's a fact indeed. So, overwriting this service is as easier as overwriting
49 | any other service. Please, follow these cookbooks.
50 | 
51 | * [Overwrite a service](http://elcodi.io/docs/cookbook/overwrite/overwrite-a-service/)


--------------------------------------------------------------------------------
/manuscript/book/coupon-architecture.md:
--------------------------------------------------------------------------------
  1 | # Coupon Architecture
  2 | 
  3 | Our coupon architecture is intended to work as a simple coupon server. All the
  4 | coupon model is decoupled from every other package, so you should be able to
  5 | work with coupons, and only with coupons.
  6 | 
  7 | In this chapter we will take a look at the different types of coupons we can
  8 | work in Elcodi. Of course, this model can evolve and get better.
  9 | 
 10 | ## Create coupon
 11 | 
 12 | If you want to create a new coupon instance, you should always use the factory
 13 | object defined in the dependency injection layer. The service is defined with
 14 | the name `elcodi.factory.coupon` and is available for injection as follows.
 15 | 
 16 | ``` yaml
 17 | services:
 18 |     my_service:
 19 |         class: My\Service\Namespace
 20 |         arguments:
 21 |             - @elcodi.factory.coupon
 22 | ```
 23 | 
 24 | a small snippet of this service could be that one
 25 | 
 26 | ``` php
 27 | $coupon = $this
 28 |     ->couponFactory
 29 |     ->create()
 30 | ```
 31 | 
 32 | Please, follow this cookbook if you need more information about elcodi factories.
 33 | 
 34 | * [How to implement a factory](http://elcodi.io/docs/cookbook/implementation/implement-a-factory/)
 35 | 
 36 | ## Coupon types
 37 | 
 38 | > Important. This part of the documentation describes how Elcodi manages the
 39 | > types involving the elcodi's Cart implementation.
 40 | 
 41 | There are several types of application in elcodi Coupons and each of them uses
 42 | a certain part of the Coupon entity. The type of the coupon can be defined using
 43 | the field `$type` of Coupon.
 44 | 
 45 | ``` php
 46 | use Elcodi\Component\Coupon\Entity\Coupon;
 47 | 
 48 | $coupon = new Coupon();
 49 | $coupon->setType($type);
 50 | ```
 51 | 
 52 | Let's take a look to each one.
 53 | 
 54 | ### Absolute value coupons
 55 | 
 56 | This is the common and default coupon type. You apply an specific discount for
 57 | the cart defined by an specific amount, for example 10 euros.
 58 | 
 59 | ``` php
 60 | use Elcodi\Component\CartCoupon\Applicator\AbsoluteCartCouponApplicator;
 61 | 
 62 | $price = ... // Money instance
 63 | 
 64 | $coupon->setType(AbsoluteCartCouponApplicator::id();
 65 | $coupon->setPrice($price);
 66 | ```
 67 | 
 68 | ### Percent coupons
 69 | 
 70 | This coupon introduces a percent discount for the final cart.
 71 | 
 72 | ``` php
 73 | use Elcodi\Component\CartCoupon\Applicator\PercentCartCouponApplicator;
 74 | 
 75 | $coupon->setType(PercentCartCouponApplicator::id();
 76 | $coupon->setDiscount(15);
 77 | ```
 78 | 
 79 | ### NxM coupons
 80 | 
 81 | This coupon is intended to be a *"buy n units and pay only m"*. Because the
 82 | system should always be opened for evolution, the configuration of this coupon
 83 | is done by using an specific syntax.
 84 | 
 85 | ``` php
 86 | use Elcodi\Component\CartCoupon\Applicator\Abstracts\AbstractMxNCartCouponApplicator;
 87 | 
 88 | $coupon->setType(AbstractMxNCartCouponApplicator::id();
 89 | $coupon->setValue('xxx');
 90 | ```
 91 | 
 92 | In this chapter we will explain how to configure these coupons. This
 93 | configuration is splitted in three blocks. Each one defines an specific part of
 94 | the coupon and they are splitted by the symbol `:`.
 95 | 
 96 | #### NxM Configuration
 97 | 
 98 | First block. Configures the NxM definition:
 99 | 
100 | * N: Units to buy
101 | * M: Units to pay
102 | 
103 | For example, 3x2 means pay 2 and buy 3. That simple.
104 | 
105 | #### Filtering Configuration
106 | 
107 | The second block aims to be the filter of the coupon. What elements should this
108 | coupon be applied on? You can filter by using product ids, category ids or
109 | manufacturer ids.
110 | 
111 | Let's see some examples with the explanation of the meaning (all of them start
112 | with Pay 2 and Buy 3):
113 | 
114 | * **3x2:p(12)** - Only applies to purchasables with id 12
115 | * **3x2:p(50,2)** - Only applies to purchasables with id 50 or 2
116 | * **3x2:c(1)** - Only applies to purchasables of category with id 1
117 | * **3x2:c(1,3)** - Only applies to purchasables of category with id 1 or 3
118 | * **3x2:m(5)** - Only applies to purchasables of manufacturer with id 5
119 | * **3x2:m(5,45)** - Only applies to purchasables of manufacturer with id 5 or 45
120 | * **3x2:c(50)&m(2)** - Only applies to purchasables of category with id 50 and
121 | manufacturer with id 2
122 | * **3x2:p(10)|m(2)|c(4,10)** - Only applies to purchasables that have id 50, or
123 | with category 4 or 10, or with manufacturer 2.
124 | 
125 | #### Modifiers Configuration
126 | 
127 | Last block. Once you've filtered, you can configure some special behaviors of
128 | your coupon. Each one of the modifiers are a simple letter at the end of the
129 | expression. You can add as many as you need, no matter the order between them.
130 | 
131 | The first group of modifiers are related to what family of Purchasables this
132 | coupon should apply with.
133 | 
134 | * P - Coupon applicable only on Products
135 | * V - Coupon applicable only on Variants
136 | * K - Coupon applicable only on Packs
137 | 
138 | You can combine them all
139 | 
140 | * PK - Coupon applicable only on Products and Packs
141 | 
142 | Lets see an example
143 | 
144 | * **3x2:c(12):PK** - Pay 2 and buy 3. Applicable only on products and packs that
145 | are from category with id 12.
146 | 
147 | The second group of modifiers are related to how to apply the coupon once all
148 | purchasable elements are selected.
149 | 
150 | By default, your MxN coupon is applied to each purchasable selected. For
151 | example, if your cart has a product 3 times and a pack 3 times, both available
152 | for a 3x2 coupon, the coupon will be applied for each one in an independent way,
153 | so you will pay 2 products and 2 packs. One of each them will be free.
154 | 
155 | * G - Group modificator. This modificator allow you to treat all purchasables as
156 | the same when applying the coupon. With the last example, you would have 6
157 | purchasables, and you would get free only the 2 most cheap (no matter if they
158 | are products or packs).
159 | 
160 | **3x2:c(12):PKG**
161 | 
162 | ### Adding a new filter
163 | 
164 | You can add a new filter by creating a new implementation of interface
165 | `Symfony\Component\ExpressionLanguage\ExpressionLanguage`.
166 | 
167 | This filter uses the ExpressionLanguage that Symfony provides, so make sure you
168 | know how it works.
169 | 
170 | This interface requires you to implement a method called registerFunction.
171 | 
172 | ``` php
173 | /**
174 |  * Interface ExpressionLanguageFunctionInterface.
175 |  */
176 | interface ExpressionLanguageFunctionInterface
177 | {
178 |     /**
179 |      * Register function.
180 |      *
181 |      * @param ExpressionLanguage $expressionLanguage Expression language
182 |      */
183 |     public function registerFunction(ExpressionLanguage $expressionLanguage);
184 | }
185 | ```
186 | 
187 | Once you have created this implementation, you need to register it in your
188 | dependency injection file with a tag.
189 | 
190 | ``` yml
191 | services:
192 |     elcodi.cart_coupon_applicator_function.custom:
193 |         class: My\Custom\Applicator\Function\Namespace
194 |         public: false
195 |         tags:
196 |             - { name: elcodi.cart_coupon_applicator_function }
197 | ```
198 | 
199 | ### Adding a new Type
200 | 
201 | You can add a new Type as well. In that case you must create a new
202 | implementation for interface
203 | `Elcodi\Component\CartCoupon\Applicator\Interfaces\CartCouponApplicatorInterface`.
204 | 
205 | This interface requires you to implement these methods.
206 | 
207 | ``` php
208 | /**
209 |  * Interface CartCouponApplicatorInterface.
210 |  */
211 | interface CartCouponApplicatorInterface
212 | {
213 |     /**
214 |      * Get the id of the Applicator.
215 |      *
216 |      * @return string Applicator id
217 |      */
218 |     public static function id();
219 | 
220 |     /**
221 |      * Can be applied.
222 |      *
223 |      * @param CartInterface   $cart   Cart
224 |      * @param CouponInterface $coupon Coupon
225 |      *
226 |      * @return bool Can be applied
227 |      */
228 |     public function canBeApplied(
229 |         CartInterface $cart,
230 |         CouponInterface $coupon
231 |     );
232 | 
233 |     /**
234 |      * Calculate coupon absolute value.
235 |      *
236 |      * @param CartInterface   $cart   Cart
237 |      * @param CouponInterface $coupon Coupon
238 |      *
239 |      * @return MoneyInterface|false Absolute value for this coupon in this cart.
240 |      */
241 |     public function getCouponAbsoluteValue(
242 |         CartInterface $cart,
243 |         CouponInterface $coupon
244 |     );
245 | }
246 | ```
247 | 
248 | Once you have implemented this method, then you need to register your new
249 | service in your dependency injection configuration file.
250 | 
251 | ``` yml
252 | services:
253 |     elcodi.cart_coupon_applicator.custom:
254 |         class: My\Custom\Applicator\Namespace
255 |         tags:
256 |             - { name: elcodi.cart_coupon_applicator }
257 | ```
258 | 
259 | ## Coupon enforcement
260 | 
261 | Another possible coupon configuration is the enforcement. The real meaning of
262 | that value is for *How the coupon is applied*. Values can be manually and
263 | automatically.
264 | 
265 | ``` php
266 | namespace Elcodi\Component\Coupon;
267 | /**
268 |  * Class ElcodiCouponTypes
269 |  */
270 | final class ElcodiCouponTypes
271 | {
272 |     /**
273 |      * @var integer
274 |      *
275 |      * Automatic enforcement
276 |      */
277 |     const ENFORCEMENT_AUTOMATIC = 1;
278 |     
279 |     /**
280 |      * @var integer
281 |      *
282 |      * Manual enforcement
283 |      */
284 |     const ENFORCEMENT_MANUAL = 2;
285 | }
286 | ```
287 | 
288 | With the first one you are creating a coupon that will be applied automatically
289 | in all carts. This doesn't mean that will be really applied to all of them, but
290 | just tried.
291 | 
292 | ## Minimum purchase
293 | 
294 | You can define that a coupon is only applicable when a cart price is above a 
295 | certain price. The way to do that is by using the property called
296 | `$minimumPurchase`. This property may be an instance of `Elcodi\Component\Currency\Entity\Money`.
297 | 
298 | ``` php
299 | /**
300 |  * Set minimum purchase
301 |  *
302 |  * @param MoneyInterface $amount Absolute Price
303 |  *
304 |  * @return $this Self object
305 |  */
306 | public function setMinimumPurchase(MoneyInterface $amount)
307 | {
308 |     $this->minimumPurchaseAmount = $amount->getAmount();
309 |     $this->minimumPurchaseCurrency = $amount->getCurrency();
310 |     return $this;
311 | }
312 | /**
313 |  * Get minimum purchase
314 |  *
315 |  * @return MoneyInterface Absolute Price
316 |  */
317 | public function getMinimumPurchase()
318 | {
319 |     return Money::create(
320 |         $this->minimumPurchaseAmount,
321 |         $this->minimumPurchaseCurrency
322 |     );
323 | }
324 | ```
325 | 
326 | ## Adding some Rules
327 | 
328 | When a Coupon is intended to be applied in a Cart and the field `$rule` is not
329 | null, then this rule is applied. Of course, if the rule execution result is
330 | false, the coupon is refused.
331 | 
332 | you can read some information about rules by following these links
333 | 
334 | * [New in Symfony 2.4: The ExpressionLanguage Component](http://symfony.com/blog/new-in-symfony-2-4-the-expressionlanguage-component)
335 | * [ExpressionLanguage Symfony Component](http://symfony.com/doc/current/components/expression_language/index.html)
336 | 


--------------------------------------------------------------------------------
/manuscript/book/dictionary.md:
--------------------------------------------------------------------------------
  1 | # Dictionary
  2 | 
  3 | In this dictionary you will find some meanings of some of our most used words.
  4 | If there is one word you don't know what is about, please ask us in out
  5 | [Gitter channel](http://gitter.im/elcodi/elcodi) and we will create the entry
  6 | as soon as possible.
  7 | 
  8 | We will very happy to help you :)
  9 | 
 10 | ### Attribute
 11 | 
 12 | Refers to a feature of a Variant.  
 13 | Please, check [Variant](#variant)
 14 | 
 15 | ### Bamboo
 16 | 
 17 | Bamboo is a simple and basic E-commerce application based on Symfony, that uses
 18 | all Elcodi components for it's own business logic. All Elcodi related best 
 19 | practices are applied and used in this project.
 20 | 
 21 | ### CartLine
 22 | 
 23 | Everytime a product or a variant is added into your cart, some information
 24 | related to this specific action must be stored. For example, if you add a
 25 | Variant and some extra information must be stored, where do you do it? Or where
 26 | do you store how many units of a product you want to buy?
 27 | 
 28 | If the relation between a Product and a Cart is persisted without any kind of
 29 | middle class, then you cannot store this information.
 30 | 
 31 | So, a CartLine is an object in the middle between any purchasable and a cart to
 32 | store information about this purchasable instance and the cart.
 33 | 
 34 | ![Cart Cartline model](images/model-cart-cartline.png)
 35 | 
 36 | ### Component
 37 | 
 38 | A component is a simple PHP Library. Only PHP Classes are placed inside this 
 39 | package and must be framework agnostic. Because this project is a Symfony
 40 | project, each component has it's own Bundle, where all libraries are exposed to
 41 | the Symfony Dependency Injection and where are bundles are created and
 42 | configured.
 43 | 
 44 | Elcodi has splitted its business logic in several components, each one 
 45 | containing specific parts of the model, and grouped semantically. CHeckout some
 46 | of them:
 47 | 
 48 | * [Cart Component](http://github.com/elcodi/Cart)
 49 | * [Product Component](http://github.com/elcodi/Product)
 50 | * [Core Component](http://github.com/elcodi/Core)
 51 | 
 52 | Some of our components are detailed and documented in this documentation.
 53 | 
 54 | * [Elcodi Components](http://elcodi.io/docs/component/)
 55 | 
 56 | And some other components are described as book chapters, describing a little
 57 | bit more its architecture and workflow.
 58 | 
 59 | * [Cart Architecture](http://elcodi.io/docs/book/cart-architecture/)
 60 | * [Product Architecture](http://elcodi.io/docs/book/product-architecture/)
 61 | 
 62 | ### Factory
 63 | 
 64 | PHP Class with one single responsibility: create a new entity instance. This
 65 | class should know as well how this entity instance must be initialized given
 66 | an specific environment
 67 | 
 68 | - My CustomerFactory initializes all my Customer new instances as females 
 69 |   because my project is focused on women.
 70 | - Other projects can overwrite this class by defining how a Customer should be
 71 |   initialized
 72 | - Because of that, the customer itself should never know about it's own
 73 |   initialization
 74 |   
 75 | To know a little bit more about factories, please follow this interesting links:
 76 | 
 77 | * [How to implement a factory](http://elcodi.io/docs/cookbook/implementation/implement-a-factory/)
 78 | * [Factory pattern in Symfony2](http://mmoreram.com/blog/2013/12/23/factory-pattern-in-symfony2/)
 79 | 
 80 | ### Plugin
 81 | 
 82 | Because Bamboo must be a project with a well-designed extension point. For such
 83 | reason, and taking advantage of how Symfony Bundles work, we have created a 
 84 | plugin engine in order to allow people overwriting and extending Bamboo in a
 85 | very simple and intuitive way.
 86 | 
 87 | When we refer to a Plugin then, we refer to these Bundles that are thought as 
 88 | Plugins, following their specification.
 89 | 
 90 | There is a full book chapter about Elcodi plugins, and this part is going to be
 91 | improved day by day with new ideas, with new developments and with new
 92 | specifications.
 93 | 
 94 | [Elcodi Plugins](http://elcodi.io/docs/book/plugins/)
 95 | 
 96 | ### Repository
 97 | 
 98 | Each entity has it's own repository. When we refer to a repository, we are
 99 | automatically referring to the Doctrine Repositories.
100 | 
101 | Each repository is created by default and defined inside the Dependency
102 | Injection service map using the structure `elcodi.repository.{entity_name}`.
103 | 
104 | To know more about Repositories in Elcodi, please check these links.
105 | 
106 | [How to implement a Repository](http://elcodi.io/docs/cookbook/implementation/implement-a-repository/)
107 | [Doctrine Repositories](http://doctrine-orm.readthedocs.org/en/latest/reference/working-with-objects.html)
108 | 
109 | ### Value
110 | 
111 | Refers to a value of an attribute and assigned to a Variant.  
112 | Please, check [Variant](#variant)
113 | 
114 | ### Variant
115 | 
116 | Sometimes a Product is not enough when we need to define something we want to 
117 | sell. Let's see an example.
118 | 
119 | * In our store we sell a T-shirt
120 | * If your T-Shirt is only sold only in red color and you only have one size, 
121 |   then that's good enough for you
122 | * But what happens when your T-shirt is available in many colors or many sizes?
123 | * Your product will still be the same T-shirt, but you need a new entity to say
124 |   that people can buy this T-shirt in red, blue and grey, and in several sizes,
125 |   like small, medium or large.
126 | * When we talk about Variant, we talk about each available combination, 
127 |   containing the original product, the color and the size.
128 | * Of course, if your have several Variants of a specific Product, people will be
129 |   able to add these variants to their carts, instead of the Product.
130 | 
131 | This is the main definition of what a Variant is, but in this case we will
132 | introduce you as well the common terms *Attribute* and *Value*. Each variant
133 | instance is a Product element combined to an Attribute and a Color.
134 | 
135 | Let's continue with the same example, but specifying a little bit.
136 | 
137 | * We have our T-shirt Product
138 | * We have created a new Attribute called Size
139 | * We have created three new values related to this Attribute, called Small,
140 | Medium and Large. All three have Size as Attribute.
141 | * We have created one new Variant, having our the T-shirt as product, and having
142 | Small as Value. Because this Value has Size as Attribute, then we can say that:
143 | 
144 | We have a new Variant called "Small T-shirt"
145 | * Product: T-shirt
146 | * Attribute: Size
147 | * Value: Small
148 | 
149 | Of course, a Variant is a *Purchasable* like Product, so you can add it into
150 | your Cart.
151 | 


--------------------------------------------------------------------------------
/manuscript/book/emails.md:
--------------------------------------------------------------------------------
1 | # Emails
2 | 
3 | All these emails are managed by the application. In this chapter we will explain
4 | what emails you will find and where are sent. You will find as well how to work
5 | with them and overwrite their content.
6 | 
7 | 


--------------------------------------------------------------------------------
/manuscript/book/features.md:
--------------------------------------------------------------------------------
 1 | # Features
 2 | 
 3 | This is the list of all features Bamboo offers you in its simple and basic
 4 | installation. This list will grow over the time, and some features will be added
 5 | by external plugins.
 6 | 
 7 | ## Store
 8 | 
 9 | * Home page, with some products
10 | * Product page, with related products
11 | * Variant page, with related products
12 | * Cart page, with all your cart information
13 | * Login and Register infrastructure for customers
14 | * Customer administration page with Addresses management
15 | * Language selection
16 | * Currency selection
17 | 
18 | ## Checkout process
19 | 
20 | * Coupons appliance
21 | * Payment method selection
22 | * Shipping method selection
23 | * Products management (increase, decrease, empty cart...)
24 | 
25 | ## Admin
26 | 
27 | * Main dashboard with some interesting metrics about your site
28 | * Customers management
29 | * Orders management, with shipping and payment tracking
30 | * Products and Variants management, with some metrics and shared comments
31 | * Categories management
32 | * Coupons management
33 | * Mailing management
34 | * Static pages management
35 | * App store, with all your plugins
36 | * Plugin management
37 | * Shipping methods management
38 | * Payment methods management
39 | * Languages management
40 | * Currencies management
41 | * Store customization panels


--------------------------------------------------------------------------------
/manuscript/book/images/category.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/category.png


--------------------------------------------------------------------------------
/manuscript/book/images/homepage.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/homepage.png


--------------------------------------------------------------------------------
/manuscript/book/images/login.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/login.png


--------------------------------------------------------------------------------
/manuscript/book/images/model-cart-cartline.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/model-cart-cartline.png


--------------------------------------------------------------------------------
/manuscript/book/images/model-cart-component.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/model-cart-component.png


--------------------------------------------------------------------------------
/manuscript/book/images/model-category.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/model-category.png


--------------------------------------------------------------------------------
/manuscript/book/images/model-order-orderline.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/model-order-orderline.png


--------------------------------------------------------------------------------
/manuscript/book/images/model-product-component.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/model-product-component.png


--------------------------------------------------------------------------------
/manuscript/book/images/product.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/product.png


--------------------------------------------------------------------------------
/manuscript/book/images/register.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/register.png


--------------------------------------------------------------------------------
/manuscript/book/images/top-bar.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/top-bar.png


--------------------------------------------------------------------------------
/manuscript/book/images/variant.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/book/images/variant.png


--------------------------------------------------------------------------------
/manuscript/book/index.md:
--------------------------------------------------------------------------------
 1 | # Elcodi Book
 2 | 
 3 | Welcome to the Elcodi Book, specially designed for all Elcodi developers with
 4 | the single purpose of providing a solid base to start coding.
 5 | 
 6 | First of all, some tips about the real meaning of Elcodi. Take your time in
 7 | these chapters. The more you understand our philosophy, the better you will code
 8 | your projects based on Elcodi.
 9 | 
10 | * [What is Elcodi](http://elcodi.io/docs/book/what-is-elcodi/)
11 | * [Why Elcodi](http://elcodi.io/docs/book/why-elcodi/)
12 | * [Philosophy](http://elcodi.io/docs/book/philosophy/)
13 | * [Standards](http://elcodi.io/docs/book/standards/)
14 | 
15 | Then, some interesting topics about implementation and configuration. In this 
16 | chapters you will understand how we have resolved some approaches and you can be
17 | part of it by adding your own business logic.
18 | 
19 | * [Quick Start](http://elcodi.io/docs/quick-start/)
20 | * [Quick Start using Vagrant](http://elcodi.io/docs/book/vagrant-quick-start/)
21 | * [Features](http://elcodi.io/docs/book/features/)
22 | * [Processes](http://elcodi.io/docs/book/processes/)
23 | * [Commands](http://elcodi.io/docs/book/commands/)
24 | * [Emails](http://elcodi.io/docs/book/emails/)
25 | * [Dictionary](http://elcodi.io/docs/book/dictionary/)
26 | * [Events](http://elcodi.io/docs/book/events/)
27 | * [Product Architecture](http://elcodi.io/docs/book/product-architecture/)
28 | * [Category Architecture](http://elcodi.io/docs/book/category-architecture/)
29 | * [Cart Architecture](http://elcodi.io/docs/book/cart-architecture/)
30 | * [Coupon Architecture](http://elcodi.io/docs/book/coupon-architecture/)
31 | * [Plugins](http://elcodi.io/docs/book/plugins/)
32 | * [Payments](http://elcodi.io/docs/book/payments/)
33 | * [Shipping](http://elcodi.io/docs/book/shipping/)
34 | 
35 | Some of our components can be used out of the box. They don't have specific
36 | E-commerce related business logic, so they can be described in an isolated way.
37 | 
38 | * [Entity Translator](http://elcodi.io/docs/component/entity-translator/)
39 | * [Media](http://elcodi.io/docs/component/media/)
40 | * [Menu](http://elcodi.io/docs/component/menu/)
41 | * [Sitemap](http://elcodi.io/docs/component/sitemap/)
42 | * [State Transition Machine](http://elcodi.io/docs/component/state-transition-machine/)
43 | * [Metrics](http://elcodi.io/docs/component/metrics/)
44 | * [Template](http://elcodi.io/docs/component/template/)
45 | 
46 | Finally, these chapters will help you about some extra elements related to the
47 | project. Interesting if you want to, not only use Elcodi as an open source
48 | project, but as a personal project, with the possibility of helping us growing
49 | and becoming better day by day
50 | 
51 | * [Translate Elcodi](http://elcodi.io/docs/book/translate-elcodi/)
52 | * [Cookbook list](http://elcodi.io/docs/cookbook/index/)
53 | * [Roadmap](http://elcodi.io/docs/book/roadmap/)
54 | * [Running tests suite](http://elcodi.io/docs/book/running-test-suite/)
55 | * [Pull Requests](http://elcodi.io/docs/book/pull-requests/)


--------------------------------------------------------------------------------
/manuscript/book/philosophy.md:
--------------------------------------------------------------------------------
  1 | # Elcodi Philosophy
  2 | 
  3 | One of the questions we are very used to responding is... why Elcodi and not any
  4 | other possible options?
  5 | 
  6 | This question is indeed bad formulated, so we've never based our philosophy in
  7 | being different from the others in a very explicit way, so the project just was
  8 | born thanks that, some years ago, none of the existing options filfilled our 
  9 | needs as a company and as a client. So, because of that, we decided to create a
 10 | new way of coding an E-commerce product.
 11 | 
 12 | We named it Elcodi.
 13 | 
 14 | For starting this chapter is fair enough to say that Elcodi goes a little futher
 15 | than a simple technological solution, so the basic needs of any technical
 16 | department are not covered only with a repository full of PHP code lines.
 17 | In Elcodi we aim to create a small foundation of thoughts and reflections
 18 | related completely with the code quality, with the software architecture and
 19 | with the open source, on top of pragmatism.
 20 | 
 21 | We bring you here some small topics.
 22 | 
 23 | ## Clean Code
 24 | 
 25 | Yes. Clean Code. How super cool is saying *clean code*, right? As developers 
 26 | we've heard this expression hundreds of times, and seems that we never give it 
 27 | enough importance to what really means Clean Code on open source. The real 
 28 | meaning is the base of our principles, and for that reason all our code (at 
 29 | least that's our goal) must be enough clean, neat, organized and documented to
 30 | make it understandable by every single developer working on Elcodi.
 31 | 
 32 | - But the code should be self-explained!
 33 | - Indeed. That makes reference to the code quality. Variables well named, code
 34 | well structured (not everything in the same line, for example), well designed
 35 | blocks and classes and methods well named as well. Have you ever heard speak on
 36 | the context change problem? Clean Code should cover this topic as well.
 37 | 
 38 | Imagine that a developer is working with Elcodi as a dependency in his vendor
 39 | folder. As a developer, he should focus only in what is really important for
 40 | him, his business logic. The other code related to his work should be enough
 41 | clear, easy and fast to comprehend in order to focus as less as possible the
 42 | developer.
 43 | 
 44 | And you know what? People is intended to understand better the human language
 45 | than the code itself. This means that if you can provide an easy comprehension
 46 | layer for anyone that only what to know something about a class or a method,
 47 | then why not? You're reducing this annoying cost of focus change.
 48 | 
 49 | - With PHPDoc documentation, both in terms of class responsibility and method
 50 | definition
 51 | - With a great definition of method input and output
 52 | - With an even better nomenclature of methods
 53 | - Using normalization as much as possible
 54 | - Using PSR standards
 55 | 
 56 | Of course, all non-code-related must be removed in order to no create visual
 57 | noise and to not introduce ambiguity.
 58 | 
 59 | ## Real pragmatism
 60 | 
 61 | We assume that to reach a goal there are always many ways. Some of them are can
 62 | be considered as good ways and could be treated as such. That's because each
 63 | possible implementation is the combination of a theoretical base and a set of
 64 | external realities far from being idyllic, for example, time, requirements and 
 65 | resources.
 66 | 
 67 | In Elcodi we think that these unfavorable conditions are always present around
 68 | us, so we have been working so far by simplifying and improving the user
 69 | experience, without forgetting about the complexity and the completeness of the
 70 | final project.
 71 | 
 72 | What does it really means?
 73 | 
 74 | - We want our code to be as much readable and understandable as possible
 75 | - We fled from complex architectures, forgetting about these structures that can
 76 | be too difficult for most part of the developers
 77 | - We are mainly focused on providing a grateful and kind experience. We want,
 78 | and is one of our most important points, reduce and mitigate the pain when
 79 | working with E-commerce.
 80 | - We are a Community-first project. This means that we are aware of how
 81 | difficult is starting with a new technology. We will there with you.
 82 | 
 83 | We work so hard to bring to the community the possibility to have a big voice.
 84 | We listen them everyday to concrete our roadmap, so they can actively
 85 | participate to the progress of the project
 86 | 
 87 | ## Community first
 88 | 
 89 | One of our virtues is that the project was born from the community, we exist
 90 | because of the community and we strongly think that the community will be, at
 91 | the end, what will make Elcodi a successful project
 92 | 
 93 | Each developer interested in our project is (and will always be) a great
 94 | opportunity for us to improve our work, so it worth spending some time helping
 95 | people with the project, evangelizing our point of view, our way of doing and
 96 | sharing lot of knowledge and fun.
 97 | 
 98 | We spend part of our effort in creating new projects based in Elcodi, feeding
 99 | the community with new use cases, with new motivated developers on growing with
100 | our philosophy and bringing people new and stronger reasons to share this path
101 | with us.
102 | 


--------------------------------------------------------------------------------
/manuscript/book/processes.md:
--------------------------------------------------------------------------------
  1 | # Processes
  2 | 
  3 | In this chapter you will find a set of Bamboo processes. A process is just a
  4 | page loaded or a specific action from an already loaded page.
  5 | 
  6 | Each entry of this chapter has the same predefined format, taking in account
  7 | that all links work having a clean Bamboo installation listening to
  8 | http://localhost:8000
  9 | 
 10 | **Given** - Initial environment and requirements  
 11 | **When** - Our elemental action  
 12 | **Then** - Actions ocurred because of that previous actions. Sent emails and 
 13 | important dispatched events are described here as well.
 14 | 
 15 | In each scenario, we'll provide as well some nice sections for you to know a
 16 | little bit more about it.
 17 | 
 18 | * Events dispatched - Events dispatched by the symfony component or any Elcodi
 19 | components
 20 | * Email sent - Emails sent by the application during this action
 21 | * Related links - Interesting links to know a little bit more about the scenario
 22 | * Nice improvements - Small tips about how to improve the scenario.
 23 | 
 24 | ## Load any page
 25 | 
 26 | All pages have a common set of elements described as follows. All elements
 27 | belong to the application, so they are applicable to all web requests.
 28 | 
 29 | **Given** - As a user, no matter the credentials  
 30 | **When** - We want to visit any application page  
 31 | **Then** - These actions happen  
 32 | 
 33 | * Request is handled by the Bamboo application, on top of the Symfony Framework,
 34 | Symfony components and Elcodi components.
 35 | * The user is loaded by using the session information
 36 | * The user credentials are checked and analyzed in order to find authentication
 37 | and authorization information.
 38 | * If the user can visit the page, then the response is created and served to the
 39 | user.
 40 | * Otherwise, you'll receive a redirection to login page
 41 | * Some user related information is loaded from database
 42 | * Some language related information is loaded from database, taking in account
 43 | the user or using stored-in-session data
 44 | * Some currency information is loaded the same way than language
 45 | * The request is processed
 46 | 
 47 | ![Top bar](images/top-bar.png)
 48 | 
 49 | Related links
 50 | 
 51 | * [HTTP Fundamentals](http://symfony.com/doc/current/book/http_fundamentals.html)
 52 | * [Symfony Security](http://symfony.com/doc/current/book/security.html)
 53 | * [Session Management](http://symfony.com/doc/current/components/http_foundation/sessions.html)
 54 | 
 55 | ## Load the home page
 56 | 
 57 | The main page, or home page, is always treated as a simple category page, having
 58 | that the way of retrieving the products is by filtering by the field `inHome`.
 59 | 
 60 | **Given** - As a user, no matter the credentials  
 61 | **When** - We visit the home page, http://localhost:8000  
 62 | **Then** - We can see the N first products  
 63 | 
 64 | ![Homepage](images/homepage.png)
 65 | 
 66 | ## Load the product page
 67 | 
 68 | The product page is one of the most important landing pages in the whole
 69 | e-commerce project. You will find all product related information and all the
 70 | needed buttons for adding the product in your Cart.
 71 | 
 72 | **Given** - As a user, no matter the credentials  
 73 | **When** - We visit a product without variants page
 74 | **Then** - All the product information is reached from the database and shown in
 75 | a single page. Because the product has no variants, you can add this product in
 76 | your cart by pushing the *add to cart* button.
 77 | 
 78 | ![Homepage](images/product.png)
 79 | 
 80 | Related links
 81 | 
 82 | - [Product Architecture](http://elcodi.io/docs/book/product-architecture/)
 83 | 
 84 | Improvements
 85 | 
 86 | - As soon as your website has any search service (Like elasticsearch or Solr),
 87 | all product-related data should be required from there instead of using
 88 | database. To do that, you should save all needed information in the search
 89 | server in order to avoid sql connection
 90 | 
 91 | ## Load the variants page
 92 | 
 93 | In this case, the product we're loading has variants, so the product itself is
 94 | only the master of different product variations (see related links). The meaning
 95 | of this page is the same than the product one, but in this case, we will load as
 96 | well all the variants information.
 97 | 
 98 | Of course, each variant
 99 | 
100 | **Given** - As a user, no matter the credentials  
101 | **When** - We visit a product with variants page
102 | **Then** - All the product information is reached from the database and shown in
103 | a single page. Each variant will provide you the information about adding it
104 | into cart, considering each variant as a product with some defined values.
105 | 
106 | ![Variant](images/variant.png)
107 | 
108 | Related links
109 | 
110 | - [Product Architecture](http://elcodi.io/docs/book/product-architecture/)
111 | 
112 | ## Load the category page
113 | 
114 | Just a search page, filtering by categories
115 | 
116 | **Given** - As a user, no matter the credentials  
117 | **When** - We want to see all products from a category, http://localhost:8000/category/women-shirts/1  
118 | **Then** - This page has the same behavior than the home page, but filtering by
119 | category.
120 | 
121 | ![Category](images/category.png)
122 | 
123 | Related links
124 | 
125 | - [Product Architecture](http://elcodi.io/docs/book/product-architecture/)
126 | 
127 | ## Register
128 | 
129 | Register a new user in the application.
130 | 
131 | **Given** - As a not logged non registered user  
132 | **When** - We want to register, http://localhost:8000/register  
133 | **Then** - once added our basic and needed information, and pressed the 
134 | *register* button, a new user is added into the database. Is important to know
135 | that our stored password is never saved plain and decrypted. We use BCrypt for
136 | that reason.
137 | 
138 | ![Register](images/register.png)
139 | 
140 | Events dispatched
141 | 
142 | * [user.register](http://elcodi.io/docs/book/events/#userregister)
143 | * [customer.register](http://elcodi.io/docs/book/events/#customerregister)
144 | 
145 | Sent emails
146 | 
147 | * [Customer registered]()
148 | 
149 | Related links
150 | 
151 | * [Bcrypt in Wikipedia](https://en.wikipedia.org/wiki/Bcrypt)
152 | * [Security Bundle Configuration](http://symfony.com/doc/current/reference/configuration/security.html)
153 | 
154 | 
155 | ## Login
156 | 
157 | Login in the application
158 | 
159 | **Given** - As a not logged non registered user  
160 | **When** - We want to log in, http://localhost:8000/login  
161 | **Then** - once added our basic and needed information, and pressed the 
162 | *login* button, the system checks that given user exists in database and that
163 | given password and stored one is the same. If they are, then the user is
164 | authenticated in current session and allowed to access into the private zone.
165 | Otherwise, the user is redirected to the same page with relevant errors.
166 | 
167 | ![Login](images/login.png)
168 | 
169 | Related links
170 | 
171 | * [Bcrypt in Wikipedia](https://en.wikipedia.org/wiki/Bcrypt)
172 | * [Security Bundle Configuration](http://symfony.com/doc/current/reference/configuration/security.html)
173 | 
174 | ## Logout
175 | 
176 | Logout from the application
177 | 
178 | **Given** - As a logged user
179 | **When** - We want to log out from the website, http://localhost:8000/logout
180 | **Then** - Once we decide to logout, we only need to remove the session
181 | credentials and the Symfony Security Component will do the rest.
182 | 
183 | Related links
184 | 
185 | * [Security Bundle Configuration](http://symfony.com/doc/current/reference/configuration/security.html)
186 | 


--------------------------------------------------------------------------------
/manuscript/book/product-architecture.md:
--------------------------------------------------------------------------------
  1 | # Product Architecture
  2 | 
  3 | One of the main blocks in Elcodi is it's Product architecture. We assume that
  4 | all projects will need to handle with it's own Product model diagram, so we
  5 | propose a single one, based on the most basic scenario and with an architecture
  6 | where you will be able to modify the model as much as you need.
  7 | 
  8 | ![Product component model](images/model-product-component.png)
  9 | 
 10 | ## Purchasable
 11 | 
 12 | Because you should be able to add anything both a product or a variant in your
 13 | cart, we created the interface `Purchasable`. A purchasable is an object (any)
 14 | you can add into your cart.
 15 | 
 16 | In Elcodi we have implemented two completed classes implementing this interface:
 17 | Product and Variant. Both implementations are part of the Product component, and
 18 | composes all the needed structure to maintain all kind of products and
 19 | variations of this.
 20 | 
 21 | ## Product
 22 | 
 23 | The main entity of this component. A product is what you are going to sell, no
 24 | matter what it is and not taking in account variations of this. For example, our
 25 | product could be a simple T-shirt. No color, no size, just a simple T-shirt.
 26 | 
 27 | Each product contains all information related to that element, like price, some
 28 | dimensions (all of them optional, of course), a description and a name, a SKU,
 29 | the stock of that object, and some extra properties. All you need to make this 
 30 | element unique enough.
 31 | 
 32 | You can create a new Product like this.
 33 | 
 34 | ``` php
 35 | use Elcodi\Component\Product\Entity\Product;
 36 | 
 37 | $product = new Product();
 38 | $product
 39 |     ->setSku('123456789')
 40 |     ->setStock(4)
 41 |     ->setName('Strawberry cake')
 42 |     ->setDescription('This is a strawberry cake');
 43 | ```
 44 | 
 45 | Of course, the right way in Elcodi is always using factories instead of creating
 46 | new instances by hand.
 47 | 
 48 | ``` php
 49 | $product = $this
 50 |     ->productFactory
 51 |     ->create()
 52 |     ->setName('Strawberry cake')
 53 |     ->setDescription('This is a strawberry cake');
 54 | ```
 55 | 
 56 | This service should have this dependency injection definition
 57 | 
 58 | ``` yaml
 59 | services:
 60 |     my_service:
 61 |         class: My\Service\Namespace
 62 |         arguments:
 63 |             - @elcodi.factory.product
 64 | ```
 65 | 
 66 | Some times our E-commerce implementation only requires this infrastructure. If
 67 | you sell for example single cakes, then each cake is a product, and that should
 68 | be enough. Don't over-engineer your domain and project too much.
 69 | 
 70 | In other cases, for example if your e-commerce is selling some retail, then each
 71 | Product will have some variations. Let's see what a variation is and how we can
 72 | implement it in Elcodi.
 73 | 
 74 | ## Variant
 75 | 
 76 | A Variant is a simple variation of a Product. Returning to the example of
 77 | T-shirts, maybe you want to sell the same T-shirt in several colors, several
 78 | sizes and several logos behind it.
 79 | 
 80 | One option is having one single product per each combination, and that would be
 81 | a good approach indeed, but then you have no way of controlling all products
 82 | that belong to the same family. For example, if all variations have the same
 83 | price then you should add it several times in several instances. As soon as this
 84 | price changes, then you need to change it all around.
 85 | 
 86 | Bad choice, right?
 87 | 
 88 | If you have only one Product called T-shirt and you create the right structure
 89 | for maintaining some Attributes and some Values, then you can create several
 90 | Variants, each one containing one or more Values. Because a Variant is a
 91 | Purchasable as well, then you can add them as well in your Cart.
 92 | 
 93 | First of all, let's see how to create a variant, assuming we have the previous
 94 | product created.
 95 | 
 96 | ``` php
 97 | use Elcodi\Component\Product\Entity\Product;
 98 | use Elcodi\Component\Product\Entity\Variant;
 99 | 
100 | $product = new Product();
101 | $product
102 |     ->setName('T-shirt, Dora the explorer')
103 |     ->setDescription('T-shirt of Dora');
104 |     
105 | $variant = new Variant
106 | $variant
107 |     ->setSku('12341234')
108 |     ->setStock(10)
109 |     ->setName('Blue XL T-shirt with the logo')
110 |     ->setProduct($product);
111 | ```
112 | 
113 | Of course, the right way in Elcodi is always using factories instead of creating
114 | new instances by hand.
115 | 
116 | ``` php
117 | $product = $this
118 |     ->productFactory
119 |     ->create()
120 |     ->setName('T-shirt, Dora the explorer')
121 |     ->setDescription('T-shirt of Dora');
122 |     
123 | $variant = $this
124 |     ->variantFactory
125 |     ->create()
126 |     ->setSku('12341234')
127 |     ->setStock(10)
128 |     ->setName('Blue XL T-shirt with the logo')
129 |     ->setProduct($product);
130 | ```
131 | 
132 | This service should have this dependency injection definition
133 | 
134 | ``` yaml
135 | services:
136 |     my_service:
137 |         class: My\Service\Namespace
138 |         arguments:
139 |             - @elcodi.factory.product
140 |             - @elcodi.factory.variant
141 | ```
142 | 
143 | In fact, that code is not useful at all, so none of these variants have
144 | attributes. Next step, creating a map of configurations for these Variants.
145 | 
146 | ## Attributes
147 | 
148 | A variant is composed by different attribute values. Let's check it out by using
149 | the last example. T-shirt of Dora the explorer is available in colors blue, red
150 | and green. Each one can be purchased in several sizes: S, M and L.
151 | 
152 | Each Variant is a Product and one of each attribute, called Value. So, there is
153 | one Variant that will have internally the Value blue of the Attribute color, and
154 | the Value S of the Attribute Size.
155 | 
156 | Assuming the piece of code we did before about product and variant...
157 | 
158 | ``` php
159 | $product = //;
160 | $variant = //;
161 | 
162 | $attribute = $this
163 |     ->attributeFactory
164 |     ->create()
165 |     ->setName('size');
166 |     
167 | $value = $this
168 |     ->valueFactory
169 |     ->create()
170 |     ->setValue('S')
171 |     ->setAttribute($attribute);
172 | 
173 | $variant->setValue($value);
174 | ```
175 | 
176 | As you can see, the relation is done between the Attribute and the Value, but
177 | because one Value can only have one Attribute, then the relation is done as well
178 | between the Variant and the Attribute.
179 | 
180 | ``` php
181 | $attribute = $variant
182 |     ->getValue()
183 |     ->getAttribute();
184 | ```
185 | 
186 | ## Manufacturer
187 | 
188 | A product (and because a Product is always the master piece of any purchasable)
189 | can have a manufacturer. The relation is easy and simple indeed, so there is no
190 | much need of explaining how to work with this entity.
191 | 
192 | ``` php
193 | $product = //;
194 | 
195 | $manufacturer = $this
196 |     ->manufacturerFactory
197 |     ->create()
198 |     ->setName('Levis');
199 |     
200 | $product->setManufacturer($manufacturer);
201 | ```
202 | 
203 | ## Categories
204 | 
205 | There is an entire chapter for that in Elcodi's book. Please, read it carefully
206 | in order to be able to work properly with categories in your project
207 | 
208 | * [Category Architecture](http://elcodi.io/docs/book/category-architecture/)
209 | 


--------------------------------------------------------------------------------
/manuscript/book/pull-requests.md:
--------------------------------------------------------------------------------
 1 | # Pull Requests
 2 | 
 3 | Elcodi is an Open Source project. This means that the community is a very
 4 | important part of the development (in fact, maybe the most important), and 
 5 | because of that each feature must be properly documented in order to make each
 6 | addition easy to understand and integrate.
 7 | 
 8 | You will find some information about how to create a pull request using github
 9 | in their 
10 | [help article](https://help.github.com/articles/creating-a-pull-request/).
11 | 
12 | ## Branch
13 | 
14 | The name of the branch should be explicative enough for everyone interested in
15 | reviewing. Github is used to propose names like `patch-1`, so please, check the
16 | name before any Pull Request.
17 | 
18 | You can use as well our format, that will help us to catalog more quickly your
19 | work.
20 | 
21 | ```
22 | feature/this-is-my-new-feature
23 | fix/fixes-this-thing
24 | typo/fixes-this-typo
25 | ```
26 | 
27 | ## Commits
28 | 
29 | Each branch can have as much commits as desired. But the question here is... how
30 | many commits do I need in order to create an acceptable Pull Request? The answer
31 | is as many as you need, but taking into account the possible usage of the git
32 | rebase interactive tool.
33 | 
34 | Developers are used to creating partial commits named `WIP` and pushing them to
35 | temporary branches. That's a good strategy if you want to ensure your daily 
36 | work, but can be a bad idea if you use these commits for your Pull Request.
37 | 
38 | ```
39 | 6d78a7b WIP
40 | 7843838 WIP
41 | d78dbaa tmp
42 | d7aa7df Some additions
43 | ```
44 | 
45 | As you can see here, these messages do not explain absolutely nothing about your
46 | work, so please check your branches before any Pull Request.
47 | 
48 | ## Commit description
49 | 
50 | How should a commit description describe our changes? Well, you can follow this
51 | structure to follow good practices.
52 | 
53 | ```
54 | This is a short description
55 | 
56 | Closes #123
57 | 
58 | Then, We can add a larger description, focused on showing the world what is this
59 | commit about. Don't hesitate to add as much information as needed.
60 | 
61 | * Finally, you can add some extra information using bullets
62 | * And more bullets
63 | * Related to this commit
64 | ```
65 | 
66 | ## PR Description
67 | 
68 | Anytime a PR is created, you should describe a small description about all
69 | things this set of commits are going to change. This is important because we
70 | should understand in a simple way what is this PR about.
71 | 
72 | Symfony introduced some time ago a small structure for providing some standard
73 | information about the PR.
74 | 
75 | | Q             | A
76 | | ------------- | ---
77 | | Bug fix?      | no
78 | | New feature?  | yes
79 | | BC breaks?    | no
80 | | Deprecations? | no
81 | | Fixed tickets | -
82 | | License       | MIT
83 | 
84 | Make sure that all your PRs start with this structure and with the right data


--------------------------------------------------------------------------------
/manuscript/book/roadmap.md:
--------------------------------------------------------------------------------
 1 | # Roadmap
 2 | 
 3 | In Elcodi we've defined a very strict Roadmap definition. We will evolve as much
 4 | as possible next years, but we will never forget old Elcodi and Bamboo
 5 | installations, so our progress will be supplemented with tons of help and
 6 | support for all our customers.
 7 | 
 8 | During the minor versions, we encourage all installations to follow all updates
 9 | in order to get new features, but all issues will be merged in the lowest branch
10 | possible.
11 | 
12 | Each new tag will be properly documented and comunicated.
13 | 
14 | ### v1.0
15 | 
16 | * Released the 22nd of September, 2015
17 | * First stable version of Elcodi, from all previousBeta versions
18 | * First stable version of Bamboo
19 | * New website of Elcodi
20 | * New documentation with basics of Elcodi
21 | 
22 | ### v1.1
23 | 
24 | * Released the 1st of January, 2016
25 | * Product of products (Multiproduct) will be introduced and implemented.
26 | * Better integration with Continuous Integration systems
27 | * Related products interface
28 | * New shop template will be added as the default one.
29 | * Template documentation will be added.
30 | * Documentation Metrics book chapter will be added.
31 | * Code Coverage of all components and bundles over 50%
32 | 
33 | ### v1.2
34 | 
35 | * Released the 1st of April, 2016
36 | * Search engine using ElasticSearch will be introduced here
37 | * Product API will be added
38 | * User API will be added
39 | * Cart API will be added
40 | * Some Media improvements, like new media types
41 | * New shop template will be added
42 | * Back panel documentation
43 | * Code Coverage of all components and bundles over 60%
44 | 
45 | ### v1.3
46 | 
47 | * Released the 1st of July, 2016
48 | * Multistore. Switch between stores in the same installation
49 | * Shop API will be added
50 | * New shop template will be added
51 | * New tempates and plugins website with tons of cool new stuff for all Elcodi
52 | and Bamboo implementations
53 | * Code Coverage of all components and bundles over 70%
54 | 
55 | ### v2.0
56 | 
57 | * Released the 1st of October, 2016
58 | * We will remove all deprecated code
59 | * Bamboo will use Symfony3 and maybe new version of Doctrine
60 | * Updated all dependencies
61 | * Marketplace
62 | * Elcodi community site will be created.
63 | * Unknown bunch of new and cool stuff
64 | * Code Coverage of all components and bundles over 80%


--------------------------------------------------------------------------------
/manuscript/book/running-test-suite.md:
--------------------------------------------------------------------------------
 1 | # Running Test Suite
 2 | 
 3 | Both projects have a set of Unit, Functional and Behavioral tests. It is important
 4 | to know how to run them all, and how to do that in a fast way
 5 | 
 6 | ## elcodi/elcodi
 7 | 
 8 | Running the test suite for elcodi/elcodi is simply one command:
 9 | 
10 | ``` bash
11 | php bin/phpunit
12 | ```
13 | 
14 | Elcodi tests are ran against folder `/tmp/Elcodi`, so a good practice in this
15 | case is to ensure that accesses to this folder are fast enough. For this reason, we can
16 | create a `tmpfs`, a mounted file system stored in volatile memory instead of a 
17 | persistent storage device.
18 | 
19 | ``` bash
20 | rm -Rf /tmp/Elcodi
21 | sudo mkdir /tmp/Elcodi
22 | sudo mount -t tmpfs -o size=512M tmpfs /tmp/Elcodi/
23 | ```
24 | 
25 | With this trick, your tests will run extremely faster than before.
26 | 
27 | Elcodi project uses as well a Testing Booster called
28 | [FixturesBoosterBundle](https://github.com/elcodi/FixturesBoosterBundle). This
29 | project overwrites the Doctrine command `doctrine:fixtures:load` with a boosted
30 | version.
31 | 
32 | In order to avoid keeping state on a temporal database you may need to remove 
33 | temporal files generated by this booster on your tmp folder:
34 | 
35 | ``` bash
36 | rm -rf /tmp/*.backup.database
37 | ```
38 | 
39 | In addition to this it is required to flush the redis database:
40 | 
41 | ``` bash
42 | redis-cli flushall
43 | ```
44 | 
45 | Problems can turn very cryptic if you are using an expired redis database.
46 | 
47 | ## elcodi/bamboo
48 | 
49 | Running the test suite for elcodi/bamboo is also simple:
50 | 
51 | ``` bash
52 | php bin/behat
53 | php bin/phpunit -c app/
54 | ```
55 | 
56 | As explained before, Bamboo tests also can be ran against a `tmpfs` unit.
57 | 
58 | ``` bash
59 | rm -Rf /tmp/Bamboo
60 | sudo mkdir /tmp/Bamboo
61 | sudo mount -t tmpfs -o size=512M tmpfs /tmp/Bamboo
62 | ```
63 | 
64 | You can do the same with the cache folder, in order to make all reads really 
65 | faster.
66 | 
67 | ``` bash
68 | rm -Rf app/cache
69 | mkdir app/cache
70 | sudo mkdir /tmp/Bamboo
71 | sudo mount -t tmpfs -o size=512M tmpfs /tmp/cache
72 | ```
73 | 
74 | If you want to run a subset of the behat tests you can specify the tag as
75 | an option:
76 | 
77 | ``` bash
78 | php bin/behat --tags="store"
79 | ```
80 | 
81 | This will only run the feature scenarios tagged with @store, e.g.:
82 | 
83 | ``` gherkin
84 | # bamboo/features/store/cart.feature
85 | @store @cart
86 | Feature: Store cart
87 |   In order to use the cart
88 |   As a visitor or logged user
89 |   I need to be able to add products into it and access the checkout
90 | 
91 |   # ...
92 | ```
93 | 
94 | A typical use case when to use this feature is when you want to
95 | run only the tests that require javascript.
96 | 


--------------------------------------------------------------------------------
/manuscript/book/standards.md:
--------------------------------------------------------------------------------
  1 | # Elcodi Standards
  2 | 
  3 | We have noticed that everyone has a different way of developing. In our team, 
  4 | some people place the braces at the end of the class definition, while other
  5 | people place them in a new line.
  6 | 
  7 | Is anyone wrong? Absolutely not, even PHP has standards since long time
  8 | ago, and besides anyone should also be able to work the way they want.
  9 | 
 10 | But in Elcodi we have some standards for our code.
 11 | 
 12 | ## Packages Structure
 13 | 
 14 | A component must be treated as a simple PHP library. This means that it must be
 15 | framework agnostic. At the beginning, Elcodi was a set of Bundles, divided by
 16 | concerns or boundaries, and implemented as a single Symfony-framework Bundle.
 17 | 
 18 | This was the root of some disagreements, and of course, like every single
 19 | implementation of Open Source, but we noticed that there was an opinion repeated
 20 | once and again by some users.
 21 | 
 22 | > This project is Framework dependent.
 23 | 
 24 | We thought that being a Symfony dependent project was a good idea, but we had to 
 25 | decide what to be dependent on. Finally, we decided that Elcodi had to be
 26 | coupled to Symfony components and Doctrine library, so we had to split between
 27 | simple PHP libraries (Components) and Symfony Framework adaptations of these
 28 | libraries (Bundles).
 29 | 
 30 | ## Component Structure
 31 | 
 32 | As we have said before, a component is just a PHP library. Think about it, we could use the Cart
 33 | classes in our own project, far from Symfony Framework, and because we don't 
 34 | want all the Framework dependencies inside our `vendor/` folder, maybe we should
 35 | only require the classes and their dependencies.
 36 | 
 37 | This is what a component is. Just classes.
 38 | 
 39 | So inside a component you will find a simple categorization of objects. All 
 40 | components follow the same structure.
 41 | 
 42 | ```
 43 | Cart
 44 |   |
 45 |   |- Entity
 46 |   |    |- Interfaces
 47 |   |    |    |- CartInterface.php
 48 |   |    |- Abstracts
 49 |   |    |    |- AbstractCart.php
 50 |   |    |- Cart.php
 51 |   |
 52 |   |- Factory
 53 |   |    |- CartFactory.php
 54 |   |
 55 |   |- Repository
 56 |   |    |- CartRepository.php
 57 |   |
 58 |   |- Services
 59 |   |    |- CartManager.php
 60 |   |
 61 |   |- Wrapper
 62 |   |    |- CartWrapper.php
 63 |   |
 64 |   |- Transformer
 65 |   |    |- CartOrderTransformer.php
 66 |   |
 67 |   |- Event
 68 |   |    |- OnOrderCreatedEvent.php
 69 |   |
 70 |   |- EventListener
 71 |   |    |- CartEventListener.php
 72 |   |
 73 |   |- EventDispatcher
 74 |   |    |- CartEventDispatcher.php
 75 |   |
 76 |   |- Controller
 77 |   |    |- ImageUploadController.php
 78 |   |
 79 |   |- Command
 80 |        |- SitemapProfileCommand.php
 81 | ```
 82 | 
 83 | This is just a sample of how a Component is structured, and how you should 
 84 | structure your project if you want to follow our way of doing things.
 85 | 
 86 | > This does not mean that this one is the best way of structuring your code, or
 87 | > does not mean that there is not another way of doing it. Is just our
 88 | > implementation and the one we suggest you.
 89 | 
 90 | ## Classes Standards
 91 | 
 92 | In order to create homogeneous code, we've defined a set of rules when creating
 93 | and naming classes.
 94 | 
 95 | ### Abstracts
 96 | 
 97 | Maybe is not the best standard, but we strongly believe that the name of a class
 98 | should explain its mission as much as possible. Because this
 99 | is an OpenSource project we must take care about all different skilled 
100 | developers so the name of an abstract class, even if it is redundant, will have
101 | the word `Abstract` at the end of the name.
102 | 
103 | ``` php
104 | abstract class AbstractFactory
105 | {
106 | }
107 | ```
108 | 
109 | Furthermore, any abstract class will be placed in a folder called `Abstracts/`,
110 | to make them easier to find.
111 | 
112 | ``` php
113 | \Elcodi\Component\Core\Factory\Abstracts\AbstractFactory
114 | ```
115 | 
116 | > The namespace must be Abstracts instead of Abstract because Abstract is a PHP
117 | > reserved keyword
118 | 
119 | 
120 | ### Traits
121 | 
122 | Same as Abstract classes. All Traits will have the word `Trait` at the end of 
123 | the name
124 | 
125 | ``` php
126 | trait DateTimeTrait
127 | {
128 | }
129 | ```
130 | 
131 | Furthermore, any trait will be placed in a folder called `Traits/`, to make them 
132 | easier to find.
133 | 
134 | ``` php
135 | \Elcodi\Component\Core\Entity\Traits\DateTimeTrait
136 | ```
137 | 
138 | > The namespace must be Traits instead of Trait because Trait is a PHP reserved 
139 | > keyword
140 | 
141 | There is a limitation in the definition of Traits in PHP, and it is that
142 | there is a collision problem of namespaces. Because they are virtually 
143 | copy/pasted to the final class, you can have some problems if you work with
144 | namespaces inside the Trait classes.
145 | 
146 | The way of solving this is never using use statements in a Trait, and always 
147 | using all the namespace when referencing a PHP namespace.
148 | 
149 | ``` php
150 | trait PriceTrait
151 | {
152 |     /**
153 |      * @var \Elcodi\Component\Currency\Entity\Interfaces\CurrencyInterface
154 |      *
155 |      * Currency for the amounts stored in this entity
156 |      */
157 |     protected $productCurrency;
158 | ```
159 | 
160 | ### Interfaces
161 | 
162 | Same as Abstract classes. All Interfaces will have the word `Interface` at the 
163 | end of the name
164 | 
165 | ``` php
166 | interface OrderInterface
167 | {
168 | }
169 | ```
170 | 
171 | Furthermore, any interface will be placed in a folder called `Interfaces/`, to 
172 | make them easier to find.
173 | 
174 | ``` php
175 | \Elcodi\Component\Cart\Entity\Interfaces\OrderInterface
176 | ```
177 | 
178 | > The namespace must be Interfaces instead of Interface because Interface is a 
179 | > PHP reserved keyword
180 | 
181 | ### Bundles
182 | 
183 | Each Bundle should avoid the magic of auto-discovering, placed in the class
184 | `Symfony\Component\HttpKernel\Bundle\Bundle`.
185 | 
186 | Yes, we're talking about these methods:
187 | 
188 | * getContainerExtension()
189 | * registerCommands()
190 | 
191 | In order to forget about magic there, and to clearly define our Bundles, we will
192 | always overwrite these methods, returning specifically the data is intended to
193 | return, even if methods are empty.
194 | 
195 | ``` php
196 | use Symfony\Component\Console\Application;
197 | use Symfony\Component\DependencyInjection\Extension\ExtensionInterface;
198 | use Symfony\Component\HttpKernel\Bundle\Bundle;
199 | 
200 | use Elcodi\Bundle\CoreBundle\DependencyInjection\ElcodiCoreExtension;
201 | 
202 | /**
203 |  * ElcodiCoreBundle Bundle
204 |  *
205 |  * This is the core of the suite.
206 |  * All available bundles in this suite could have this bundle as a main
207 |  * dependency.
208 |  */
209 | class ElcodiCoreBundle extends Bundle
210 | {
211 |     /**
212 |      * Returns the bundle's container extension.
213 |      *
214 |      * @return ExtensionInterface The container extension
215 |      */
216 |     public function getContainerExtension()
217 |     {
218 |         return new ElcodiCoreExtension();
219 |     }
220 | 
221 |     /**
222 |      * Register Commands.
223 |      *
224 |      * Disabled as commands are registered as services
225 |      *
226 |      * @param Application $application An Application instance
227 |      */
228 |     public function registerCommands(Application $application)
229 |     {
230 |         return;
231 |     }
232 | }
233 | ```
234 | 
235 | ## Dependency Injection
236 | 
237 | We care as well on how Elcodi services are defined in the Symfony 
238 | Dependency Injection container, in order to make easier for the final user to
239 | remember the name of the service given the namespace of the class.
240 | 
241 | First of all what you need to know is that all services in Elcodi ecosystem 
242 | start with `elcodi.`.
243 | 
244 | For example
245 | 
246 | ``` yaml
247 | elcodi.event_dispatcher.cart
248 | elcodi.manager.cart
249 | ```
250 | 
251 | We have structured all definitions in two, three or four levels.
252 | 
253 | ### Two levels services
254 | 
255 | Elcodi specific and most important services in Elcodi ecosystem. These services
256 | cannot be grouped by any kind of *namespace* because they are not an 
257 | implementation of any family.
258 | 
259 | ``` yaml
260 | elcodi.languages
261 | elcodi.languages_iso
262 | elcodi.languages_iso_array
263 | elcodi.locale
264 | ```
265 | 
266 | ### Three levels services
267 | 
268 | Most of services will have three levels of definition. Let's analyze previous
269 | examples:
270 | 
271 | ``` yaml
272 | elcodi.event_dispatcher.cart
273 | ```
274 | 
275 | **First level** is always `elcodi`. This will help you identifying all Elcodi's
276 | definition spectre.
277 | 
278 | **Second level** is the group or the final meaning of such service. For example,
279 | in this example our service will be an EventDispatcher.
280 | We have some examples of different kind of services in our project
281 | 
282 | ``` yaml
283 | elcodi.event_dispatcher.cart
284 | elcodi.event_listener.address_clone_update_carts
285 | elcodi.manager.cart
286 | elcodi.wrapper.cart
287 | elcodi.factory.cart
288 | elcodi.repository.cart
289 | elcodi.object_manager.cart
290 | elcodi.director.cart
291 | elcodi.transformer.cart_order
292 | ```
293 | 
294 | **Third level** is the name of given type. In last example we were creating, for
295 | example, the cart factory, or the cart event dispatcher. This last element has
296 | nothing to do with the name of the component, and must be extremely related with
297 | the content of the class.
298 | 
299 | ### Small classes and methods
300 | 
301 | Each class should be small enough to contain specific information. Remember to
302 | use small methods (no more than 20 lines) and to take care of their complexity.
303 | The more complex a method is, the harder to understand what is all
304 | about.
305 | 
306 | ### PHPDoc
307 | 
308 | This is an important part of the project.
309 | 
310 | All methods must be explained for humans. Some people think that the code should
311 | be self-explanatory, and we agree on that. This doesn't mean that all people 
312 | should read the code to understand what a method is intended for.
313 | 
314 | Pretending them to understand our method by its code is to prevent them to focus 
315 | on their own business logic, and can hinder development speed.
316 | 
317 | All methods must follow these rules as well, related to PHP Doc format
318 | 
319 | ``` php
320 | /**
321 |  * This is my detailed description about what my code is intended for
322 |  * I can use as many lines as possible.
323 |  * I repeat, as many lines as possible.
324 |  *
325 |  * @param MyObject $myObject My object description
326 |  * @param string   $info     Some information
327 |  * @param integer  $number   Some number
328 |  *
329 |  * @return Factory Description of the result
330 |  *
331 |  * @throws AnException Scenario when this exception is thrown
332 |  */
333 | ```
334 | 
335 | Using this kind of blocks there are some tips we all need to take into account.
336 | 
337 | * There is a space between all blocks
338 | * The order is: Description, Params, Return and Exceptions
339 | * All params should be aligned as shown in the example
340 | * Never use @inheritBlock. It is not useful at all and makes the
341 | comprehension of the code so difficult
342 | 
343 | ## Tools
344 | 
345 | We provide you a way of converting your way of programming to ours. Why don't 
346 | you use these tools?
347 | 
348 | ### PHP-CS-Fixer
349 | 
350 | * (Github repository)[https://github.com/FriendsOfPHP/PHP-CS-Fixer]
351 | 
352 | This library analyzes all the PHP source and tries to fix coding standards 
353 | issues, using a custom definition set in the root of the project.
354 | 
355 | ``` php
356 | <?php
357 | 
358 | return Symfony\CS\Config\Config::create()
359 |     // use SYMFONY_LEVEL:
360 |     ->level(Symfony\CS\FixerInterface::SYMFONY_LEVEL)
361 |     // and extra fixers:
362 |     ->fixers(array(
363 |         'concat_with_spaces',
364 |         'multiline_spaces_before_semicolon',
365 |         'short_array_syntax',
366 |         '-remove_lines_between_uses'
367 |     ))
368 |     ->finder(
369 |         Symfony\CS\Finder\DefaultFinder::create()
370 |             ->in('src/')
371 |     )
372 | ;
373 | ```
374 | 
375 | This library is a dependency of the project, but only in development 
376 | environment, so while you are developing, if you have already updated your 
377 | composer dependencies, you can run the fixer as follows
378 | 
379 | ``` bash
380 | php bin/php-cs-fixer fix
381 | ```
382 | 
383 | Because the dependency is set using an specific version of the code, all 
384 | developers will fix the code the same way.
385 | 
386 | ### PHP-Formatter
387 | 
388 | * (Github repository)[https://github.com/mmoreram/php-formatter]
389 | 
390 | Another simple php formatter. This one will just format your class headers, 
391 | setting the project headers in your PHP classes, and will sort all use statements in
392 | order to comply with a given specification.
393 | 
394 | This library is a dependency of the project, but only in development 
395 | environment, so while you are developing, if you have already updated your 
396 | composer dependencies, you can run the fixer as follows:
397 | 
398 | ``` bash
399 | php bin/php-formatter formatter:use:sort src/
400 | php bin/php-formatter formatter:header:fix src/
401 | ```
402 | 
403 | Because the dependency is set using an specific version of the code, all 
404 | developers will fix the code the same way.
405 | 


--------------------------------------------------------------------------------
/manuscript/book/templates.md:
--------------------------------------------------------------------------------
1 | # Templates


--------------------------------------------------------------------------------
/manuscript/book/translate-elcodi.md:
--------------------------------------------------------------------------------
  1 | # Translate Elcodi
  2 | 
  3 | Elcodi is a worldwide project, and should be understandable by any interested
  4 | developer or final user. Because of that, we want to care about all languages
  5 | and translations.
  6 | 
  7 | But how you can do it?
  8 | 
  9 | ## Translation Server
 10 | 
 11 | Elcodi works with a project called
 12 | [Translation Server](https://github.com/mmoreram/translation-server). This
 13 | project provides you a small set of console commands that will enable you to
 14 | check better how complete is translations for each defined language.
 15 | 
 16 | Check the documentation of that project in the same repository.
 17 | 
 18 | ## Listing resources
 19 | 
 20 | First of all you should check all Elcodi's translation resources. In these
 21 | resources we include translations from our Bamboo project, including both Admin
 22 | panel and our default Front template. We actually include some of our default
 23 | Plugins.
 24 | 
 25 | To have the complete list of all these resources, you can use the console.
 26 | 
 27 | ``` bash
 28 | $ php app/console translation:list-resources
 29 | 
 30 | Directories list :
 31 |     - %kernel.root_dir%/../src/Elcodi/Admin/CoreBundle/Resources/translations
 32 |     - %kernel.root_dir%/../src/Elcodi/Store/CoreBundle/Resources/translations
 33 |     - %kernel.root_dir%/../src/Elcodi/Common/CommonBundle/Resources/translations
 34 |     - %kernel.root_dir%/../src/Elcodi/Plugin/GoogleAnalyticsBundle/Resources/translations
 35 |     - %kernel.root_dir%/../src/Elcodi/Plugin/PinterestBundle/Resources/translations
 36 |     - %kernel.root_dir%/../src/Elcodi/Plugin/ProductCsvBundle/Resources/translations
 37 |     - %kernel.root_dir%/../src/Elcodi/Plugin/StoreSetupWizardBundle/Resources/translations
 38 |     - %kernel.root_dir%/../src/Elcodi/Plugin/DisqusBundle/Resources/translations
 39 |     - %kernel.root_dir%/../src/Elcodi/Plugin/TwitterBundle/Resources/translations
 40 |     - %kernel.root_dir%/../src/Elcodi/Plugin/FacebookBundle/Resources/translations
 41 |     - %kernel.root_dir%/../src/Elcodi/Plugin/StoreTemplateBundle/Resources/translations
 42 |     - %kernel.root_dir%/../src/Elcodi/Plugin/PaypalWebCheckoutBundle/Resources/translations
 43 |     - %kernel.root_dir%/../src/Elcodi/Plugin/FreePaymentBundle/Resources/translations
 44 |     - %kernel.root_dir%/../src/Elcodi/Plugin/StripeBundle/Resources/translations
 45 | done!
 46 | ```
 47 | 
 48 | ## Languages
 49 | 
 50 | Elcodi works with a preset of languages. These languages are defined in a file
 51 | called [`.translation.yml`](https://github.com/elcodi/bamboo/blob/master/.translation.yml).
 52 | In this file, Elcodi defines the base of all languages we will work with. If
 53 | your language is not included, please send a Pull Request in order to add it as
 54 | soon as possible.
 55 | 
 56 | English is the main language, so the percentage of it should be complete.
 57 | You can check how translated is each language by using the translation-server
 58 | console command.
 59 | 
 60 | ``` bash
 61 | $ bin/translation-server translation:server:view
 62 | 
 63 | [Trans Server] Command started at Mon, 02 Nov 2015 17:24:36 +0100
 64 | [Trans Server] Translations for [en] is 100% completed. 0 missing
 65 | [Trans Server] Translations for [de] is 99.57% completed. 4 missing
 66 | [Trans Server] Translations for [ca] is 99.57% completed. 4 missing
 67 | [Trans Server] Translations for [es] is 99.57% completed. 4 missing
 68 | [Trans Server] Translations for [fr] is 78.36% completed. 203 missing
 69 | [Trans Server] Translations for [it] is 76.44% completed. 221 missing
 70 | [Trans Server] Translations for [fi] is 76.23% completed. 223 missing
 71 | [Trans Server] Translations for [nl] is 0% completed. 938 missing
 72 | [Trans Server] Translations for [eo] is 0% completed. 938 missing
 73 | [Trans Server] Translations for [gl] is 0% completed. 938 missing
 74 | [Trans Server] Translations for [eu] is 0% completed. 938 missing
 75 | [Trans Server] Command finished in 1439 milliseconds
 76 | [Trans Server] Max memory used: 17301504 bytes
 77 | 
 78 | ```
 79 | 
 80 | ## Completing translations
 81 | 
 82 | Adding some translations to an existent language is so simple. Of course, as you
 83 | have done since now, you can check the file where the translation is missing
 84 | (can be so difficult or tricky) and add your translation. In Bamboo this process
 85 | will be much easier because all our translation files are sorted alphabetically,
 86 | but even that, maybe you only want to add some translations in your language, no
 87 | matter where the translation is placed.
 88 | 
 89 | In that case, we have a very simple way of adding *random* translations in your
 90 | language by using as well a translation-server console command.
 91 | 
 92 | ``` bash
 93 | $ bin/translation-server translation:server:add
 94 | 
 95 | [Trans Server] Command started at Mon, 02 Nov 2015 17:43:42 +0100
 96 | [Trans Server] Language : fr
 97 | [Trans Server] Key : admin.identity.section.logo.description
 98 | [Trans Server] Original : Here you can add an image with your logo. Please use the maximum quality posible.
 99 | [Trans Server] Translation : 
100 | ```
101 | 
102 | To know a little bit more about all the possibilities this command brings you, 
103 | read its [documentation](https://github.com/mmoreram/translation-server/blob/master/README.md#asking-for-new-translations)
104 | 
105 | ## Adding translations
106 | 
107 | The easiest way of adding a new language from the scratch is by copying the
108 | english translation files to your language. By using this method, you will only
109 | have to overwrite the original value to the translated one.
110 | 
111 | Anyway, if your language is inserted as a Bamboo language in the
112 | `.translation.yml` file, you can just use the previous command 
113 | `translation:server:add` and forget about how internal files are disposed.


--------------------------------------------------------------------------------
/manuscript/book/vagrant-quick-start.md:
--------------------------------------------------------------------------------
 1 | # Vagrant Quick Start
 2 | 
 3 | Bamboo also offer the possibility to try it in a fast way using [Vagrant](https://www.vagrantup.com).
 4 | 
 5 | Vagrant is a tool based on [VirtualBox](https://www.virtualbox.org) used to reproduce the same environment and share
 6 | it with the team, so if you want start building your next ecommerce from bamboo, the VM will give your team a warranty
 7 | about the environment.
 8 | 
 9 | Bamboo also uses the [Ansible](http://www.ansible.com/) [provisioner](https://docs.vagrantup.com/v2/provisioning/ansible.html)
10 | to help you configuring the environment correctly, so you don't need to configure it everytime you need to recreate
11 | the virtual machine.
12 | 
13 | ## Requirements
14 | 
15 |  1. [download](https://www.virtualbox.org/wiki/Downloads) and install VirtualBox
16 |  2. [download](http://www.vagrantup.com/downloads) and install Vagrant
17 |  3. [install](http://docs.ansible.com/ansible/intro_installation.html) Ansible
18 | 
19 | ## Usage
20 | 
21 | Its usage is simple and is based on three commands:
22 | 
23 | ```
24 | $ cd /path/to/your/bamboo
25 | $ cd vagrant
26 | $ vagrant up
27 | ```
28 | 
29 | The output you'll see is the *provisioning* system, it will give you an "ok" when completed.
30 | 
31 | If it doesn't finish correctly don't worry, just use the `vagrant provision` to restart
32 | the provisioning process.
33 | 
34 | Once completed you'll be able to access to your bamboo store at http://10.10.10.10/app_dev.php/
35 | 
36 | It's not public, 10.10.10.10 is just the address if your local machine.
37 | 
38 | > If you need to change it, destroy the machine and change the IP in the Vagrantfile.
39 | 
40 | Well, now that you have your local bamboo store you can work on local files and them will
41 | be synced with the same files on the virtual machine.
42 | 
43 | When you complete your changes run a
44 | 
45 | ```
46 | $ cd /path/to/your/bamboo
47 | $ cd vagrant
48 | $ vagrant suspend
49 | ```
50 | 
51 | to shut down the virtual machine leaving changes
52 | untouched, and to restart it the day after just do a
53 | 
54 | ```
55 | $ cd /path/to/your/bamboo
56 | $ cd vagrant
57 | $ vagrant resume
58 | ```
59 | 
60 | If you do something wrong with the environment don't worry, it's a virtual machine so won't affect
61 | your local environment, if something goes wrong you can always do a `vagrant destroy` to destroy
62 | the virtual machine and after recreate it using `vagrant up`.
63 | 
64 | > **Attention:** the vagrant up will take time because recreates everytime the virtual machine and
65 | run the provisioning, so do it only when necessary.
66 | 
67 | ## SSH Access
68 | 
69 | If you need to access to the environment (for cron jobs, daemon processes, etc...), Vagrant gives
70 | the possibility to access with a simple command:
71 | 
72 | ```
73 | $ cd /path/to/your/bamboo
74 | $ cd vagrant
75 | $ vagrant ssh
76 | ```
77 | 


--------------------------------------------------------------------------------
/manuscript/book/what-is-elcodi.md:
--------------------------------------------------------------------------------
 1 | # What is Elcodi
 2 | 
 3 | Welcome to Elcodi.
 4 | 
 5 | In this chapter we aim to explain you some basic internals about Elcodi and some
 6 | nice reasons about how this tool can be really useful if you're interested in
 7 | E-commerce and Symfony.
 8 | 
 9 | Elcodi is a project born in Barcelona in the year 2014 as an open source
10 | project. At the beginning was born as an alternative of other existent projects
11 | non-based on Symfony, to create in a very efficient and fast way E-commerce 
12 | projects. After some months it became a nice and cool option in the Symfony
13 | ecosystem.
14 | 
15 | The main goal of the project is propose a complete base to the final user
16 | (developer) for building e-commerce projects, following some patterns and
17 | thoughts, born to satisfy the developer and bring him a very painless, efficient
18 | and fast working experience.
19 | 
20 | * [Install Elcodi](http://elcodi.io/docs/quick-start/)
21 | 
22 | When we talk about Elcodi as a complete developing tool, we don't mean that we
23 | provide all external implementations, integrations and bridges, but the project
24 | itself is a platform and is thought to make all the community participant,
25 | creating these integrations, using a great Plugin definition and implementation,
26 | and feeding the ecosystem in a very healthy way.
27 | 
28 | * [Plugins](http://elcodi.io/docs/book/plugins/)
29 | 
30 | Elcodi proposes a set of common features, specially implemented to provide a
31 | basic solution for all E-commerce implementation. Basic doesn't mean
32 | insufficient nor incomplete, but essential.
33 | 
34 | * [Features](http://elcodi.io/docs/book/features/)
35 | * [Processes](http://elcodi.io/docs/book/processes/)
36 | 
37 | Of couse, in Elcodi, apart from offering all this technological material, we
38 | want to provide our experience when implementing new feature in our code, adding
39 | our way of working and our methodologies. This working method is based in a very
40 | pragmatic thought, fleeing ephemeral and transient theories, and focusing on 
41 | what is interesting in terms of developer and community.
42 | 
43 | We thought it important that your experience as a member, department or company
44 | should be enough to make interesting and positive the fact of working with
45 | Elcodi, so we have created a set of basic principles that we have as a project.
46 | 
47 | * [Philosophy](http://elcodi.io/docs/book/philosophy/)
48 | * [Pragmatic Driven Development](http://mmoreram.com/blog/2014/10/26/pdd-pragmatic-driven-development-english/)
49 | 
50 | We highly recommend you to install Elcodi, and try it, ask us and enjoy with
51 | the experience of working with a young community, excited and willing to change
52 | the way people is intended to work with concepts like Cart, Product or even
53 | Payment Platform. No more pain!
54 | 
55 | Elcodi is a living style and we encourage you to join us, being part of our
56 | community and learning best practices, techniques and patterns existing in
57 | Symfony.
58 | 


--------------------------------------------------------------------------------
/manuscript/book/why-elcodi.md:
--------------------------------------------------------------------------------
 1 | # Why Elcodi
 2 | 
 3 | In this chapter we will show you how Elcodi can fulfill your project needs, by
 4 | explaining you our strength and weakness, and by listing you some points you
 5 | can explain to the business department.
 6 | 
 7 | ## Strength
 8 | 
 9 | * The project is Symfony based. This can be hard at the beginning if your team
10 | is not ready for Symfony, but is a great opportunity for your company to start
11 | growing as a technological company by using the spectacular framework.
12 | * The project started with one single focus: to solve the E-commerce problem by
13 | using a simple but complex base. Simple because is easy to understand, complex
14 | because you can do as many implementations as you need, as much complex as you
15 | desire.
16 | * The project is created and accurately maintained by developers for developers. 
17 | This means that our focus is not only de business layer, but the technical layer
18 | as well. Part of Elcodi team come from many exit cases of the E-commerce world,
19 | so we cover both parts pretty good.
20 | * The project is developer friendly, so E-commerce projects will not a pain 
21 | anymore.
22 | * The project follows a scalable architecture. Your development resources will
23 | not increment at all with the time. This means less time and more money to spend
24 | in your own domain (what really matters)
25 | * The project is built on top of open source, so the community will support you
26 | in all your problems and doubts.
27 | * The project have been free from the beginning and until the end, using a very
28 | open [MIT license](https://opensource.org/licenses/MIT)
29 | * The project is alive. This means that will become better day by day, using
30 | a very strict [versioning model](http://semver.org/). Every 2 months a new
31 | release will be proposed by the core team and discussed with the community.
32 | * You company will acquire a community-based culture. You will find that being
33 | side by side with that community allow you to grow healthy and hand by hand with
34 | last trendings.
35 | * The project's company, Elcodi Networks, is focused only in making the project
36 | bigger day by day, providing exclusive open source support. You'll never be
37 | alone.
38 | * The project's documentation is alive as well. It will be improved by us and
39 | translated to as many languages as needed.
40 | * We will take care about improving the core, improving the documentation and
41 | fixing all bugs encountered by our core team, as well as managing all bugs fixed
42 | by the community
43 | * We are other projects friendly. Many integrations with other projects will be
44 | available for you! We will fight hard for that!
45 | * Elcodi core team is ready for you to join them. Say hello in
46 | [Gitter's Elcodi room](http://gitter.im/elcodi/elcodi) and let them helping you
47 | with your project!
48 | 
49 | ## Weaknesses
50 | 
51 | * The project is young. This means that we've been working so hard on our core
52 | and philosophy. This means as well that we have the power to do everything as we
53 | wish and as good as we can.
54 | * The project's community is not big enough. Well, which one was big at the 
55 | beginning?
56 | * The project's plugin and template repository is not big enough. This base will 
57 | grow with the time, so this is only about making the project bigger and bigger,
58 | and the repository will automatically grow with us
59 | 


--------------------------------------------------------------------------------
/manuscript/component/index.md:
--------------------------------------------------------------------------------
 1 | # Components
 2 | 
 3 | Each Component/Bundle will be properly described here. This format will be 
 4 | applied in each one, in order to make easier for the reader to follow the 
 5 | content.
 6 | 
 7 | * What is the package intended for
 8 | * What offers
 9 | * Detailed documentation
10 | * Some links and next steps
11 | 
12 | # Components documentation
13 | 
14 | * [Entity Translator](http://elcodi.io/docs/component/entity-translator/)
15 | * [Media](http://elcodi.io/docs/component/media/)
16 | * [Menu](http://elcodi.io/docs/component/menu/)
17 | * [Sitemap](http://elcodi.io/docs/component/sitemap/)
18 | * [State Transition Machine](http://elcodi.io/docs/component/state-transition-machine/)
19 | * [Metrics](http://elcodi.io/docs/component/metrics/)
20 | * [Template](http://elcodi.io/docs/component/template/)


--------------------------------------------------------------------------------
/manuscript/component/media.md:
--------------------------------------------------------------------------------
  1 | # Media
  2 | 
  3 | Manage your media entities.
  4 | 
  5 | * [Component Repository](https://github.com/elcodi/Media)
  6 | * [Bundle Repository](https://github.com/elcodi/MediaBundle)
  7 | 
  8 | Of course, what is an E-commerce without images management. We are not focused 
  9 | on that, but we have created a tiny and simple image manager, that will provide
 10 | you an easy way of image upload and resize.
 11 | 
 12 | ## What offers
 13 | 
 14 | This component mainly contains routes as public resources. You will be able as
 15 | well to modify the way images are resized by using adapters, and a set of events
 16 | for image manipulation.
 17 | 
 18 | You will find as well the minimum implementation of Image and File entity needed
 19 | to make it work.
 20 | 
 21 | ## Upload an image: Route
 22 | 
 23 | First step for managing images is the uploading process. At the end, it is only
 24 | a controller proposed by the framework with an specific route defined.
 25 | 
 26 | If we take a look at Bamboo we will discover that we really have this route 
 27 | defined in file `routing_admin.yml`.
 28 | 
 29 | ``` yaml
 30 | admin_media:
 31 |     resource: "@AdminMediaBundle/Resources/config/routing.yml"
 32 | ```
 33 | 
 34 | of course, this piece of code is just an inclusion of an external `yaml` file,
 35 | provided by the bundle `MediaBundle`. Such file contains this code.
 36 | 
 37 | ``` yaml
 38 | #
 39 | # Routing
 40 | #
 41 | 
 42 | elcodi.route.image_upload:
 43 |     path: /images/upload
 44 |     methods: POST
 45 |     defaults:
 46 |         _controller: elcodi.controller.image_upload:uploadAction
 47 |         
 48 | elcodi.route.image_resize:
 49 |     path: /images/{id}/resize/{height}/{width}/{type}.{_format}
 50 |     methods: GET
 51 |     defaults:
 52 |         _controller: elcodi.controller.image_resize:resizeAction
 53 | 
 54 | elcodi.route.image_view:
 55 |     path: /images/{id}/render.{_format}
 56 |     methods: GET
 57 |     defaults:
 58 |         _controller: elcodi.controller.image_resize:resizeAction
 59 |         height: 0
 60 |         width: 0
 61 |         type: 0
 62 | 
 63 | ```
 64 | 
 65 | Let's focus only in the first route. Take in account that this route is defined
 66 | only as `POST`.
 67 | 
 68 | By default, this controller will check a field called `file`, but you can change
 69 | this value by overwriting the bundle configuration value
 70 | 
 71 | ``` yaml
 72 | elcodi_media:
 73 |     images:
 74 |         upload:
 75 |             field_name: file
 76 | ```
 77 | 
 78 | This value will be available in your container as a parameter with name
 79 | `elcodi.image_upload_field_name`.
 80 | 
 81 | ## Upload an image: Response
 82 | 
 83 | Once you have uploaded your image, you will receive a response depending on the
 84 | action result.
 85 | 
 86 | If the upload process has been success, you will receive this response
 87 | 
 88 | ``` json
 89 | {  
 90 |    "status":"ok",
 91 |    "response":{  
 92 |       "id":19,
 93 |       "extension":"jpg",
 94 |       "routes":{  
 95 |          "view":"\/images\/{id}\/render.{_format}",
 96 |          "resize":"\/images\/{id}\/resize\/{height}\/{width}\/{type}.{_format}",
 97 |          "delete":"\/admin\/media\/image\/{id}\/delete"
 98 |       }
 99 |    }
100 | }
101 | ```
102 | 
103 | Otherwise, you will have a fail response
104 | 
105 | ``` json
106 | {  
107 |    "status":"ko",
108 |    "response":{  
109 |       "id":19,
110 |       "extension":"jpg",
111 |       "routes":{  
112 |          "view":"\/images\/{id}\/render.{_format}",
113 |          "resize":"\/images\/{id}\/resize\/{height}\/{width}\/{type}.{_format}",
114 |          "delete":"\/admin\/media\/image\/{id}\/delete"
115 |       }
116 |    }
117 | }
118 | ```
119 | 
120 | ## View an image
121 | 
122 | Once your image, you can access to it using an already built in route.
123 | 
124 | ## Resize an image


--------------------------------------------------------------------------------
/manuscript/component/state-transition-machine.md:
--------------------------------------------------------------------------------
  1 | # State Transition Machine
  2 | 
  3 | Add states in your entities.
  4 | 
  5 | * [Component Repository](https://github.com/elcodi/StateTransitionMachine)
  6 | * [Bundle Repository](https://github.com/elcodi/StateTransitionMachineBundle)
  7 | 
  8 | Can your entity change its states? This component will help you to implement 
  9 | this in a very decoupled way, providing you a very simple way for definition of
 10 | these states and a very easy way of managing them.
 11 | 
 12 | ## What offers
 13 | 
 14 | Offers all the transition machine model classes, as well as all the service 
 15 | layer for it management, or a complete set of events dispatched during all 
 16 | transitions between states.
 17 | 
 18 | ## Usage
 19 | 
 20 | This component provides you a State Transition Machine for your entities. To
 21 | understand what is a State Transition Machine, let's see an example about a use
 22 | case.
 23 | 
 24 | Let's figure out we are working with a Order object. We want to give some states
 25 | to this Order, like "new", "paid" and "shipped". Well, this is the perfect
 26 | scenario for this component. The only thing you must define is the set of states
 27 | and how you should jump from one to another.
 28 | 
 29 | Let's see an example.
 30 | 
 31 | ```php
 32 | $configuration = [
 33 |     'new', 'pay', 'paid',
 34 |     'paid', 'ship', 'shipped',
 35 |     'shipped', 'receive', 'received',
 36 | ];
 37 | ```
 38 | 
 39 | You have four states here.
 40 | * new: First state or point of entry
 41 | * paid: The order is paid
 42 | * shipped: The order is shipped but is not received yet
 43 | * received: The order is received
 44 | 
 45 | And we have three transitions between these states.
 46 | * pay: We pay an order
 47 | * ship: We ship an order
 48 | * receive: A ship is being received
 49 | 
 50 | ## Machine Builder
 51 | 
 52 | So, this component provides a way to play with all this information in a very
 53 | single way, providing as well one machine for each configuration, identified by
 54 | a string. Let's see an example of how to build a useful Machine for our project.
 55 | 
 56 | ``` php
 57 | <?php
 58 | 
 59 | use Elcodi\Component\StateTransitionMachine\Factory\MachineFactor;
 60 | 
 61 | $machineIdentifier = 'order_states';
 62 | $pointOfEntry = 'new';
 63 | $machineFactory = new MachineFactory;
 64 | $configuration = [
 65 |     'new', 'pay', 'paid',
 66 |     'paid', 'ship', 'shipped',
 67 |     'shipped', 'receive', 'received',
 68 | ];
 69 | 
 70 | $machineBuilder = new MachineBuilder(
 71 |     $machineFactory,
 72 |     $machineIdentifier,
 73 |     $configuration,
 74 |     $pointOfEntry
 75 | );
 76 | $machine = $machineBuilder->compile();
 77 | ```
 78 | 
 79 | To build a MachineCompiler we need this information:
 80 | * Machine Factory: The factory that the MachineBuilder will use to build a new
 81 | Machine instance
 82 | * Machine identifier: The identifier of the machine. This value must be unique
 83 | * Configuration: The states definition. This parameter must be an array of
 84 | edges, and each edge must be an array with this elements: `from state`,
 85 | `transition name` and `to state`.
 86 | * Point of Entry: The first state to add once the object is initialized
 87 | 
 88 | ## Machine
 89 | 
 90 | Once the MachineBuilder is compiled, this method returns us a MachineInterface
 91 | implementation, with the possibility of using 4 methods.
 92 | 
 93 | ``` php
 94 |     /**
 95 |      * Get machine id
 96 |      *
 97 |      * @return string Machine identifier
 98 |      */
 99 |     public function getId();
100 | 
101 |     /**
102 |      * Get point of entry
103 |      *
104 |      * @return string Point of entry
105 |      */
106 |     public function getPointOfEntry();
107 | 
108 |     /**
109 |      * Applies a transition from a state
110 |      *
111 |      * @param string $startStateName Start state name
112 |      * @param string $transitionName Transition name
113 |      *
114 |      * @return Transition Transition created
115 |      *
116 |      * @throws TransitionNotAccessibleException Transition not accessible
117 |      * @throws TransitionNotValidException      Invalid transition name
118 |      */
119 |     public function transition(
120 |         $startStateName,
121 |         $transitionName
122 |     );
123 | 
124 |     /**
125 |      * Reaches a state given a start state
126 |      *
127 |      * @param string $startStateName Start state name
128 |      * @param string $finalStateName Final state name
129 |      *
130 |      * @return Transition Transition created
131 |      *
132 |      * @throws StateNotReachableException State is not reachable
133 |      */
134 |     public function reachState(
135 |         $startStateName,
136 |         $finalStateName
137 |     );
138 | ```
139 | 
140 | Given the last example with the last configuration, lets try to do apply the
141 | `pay` transition from the `new` state using the `transition` method.
142 | 
143 | ``` php
144 | echo $machine->getId();
145 | // = order_states
146 | 
147 | echo $machine->getPointOfEntry();
148 | // = new
149 | 
150 | $transition = $machine->transition('unpaid', 'pay');
151 | echo get_class($transition);
152 | // = \Elcodi\Component\StateTransitionMachine\Definition\Transition
153 | 
154 | echo $transition->getName();
155 | // = pay
156 | 
157 | echo $transition->getStart()->getName();
158 | // = new
159 | 
160 | echo $transition->getFinal()->getName();
161 | // = paid
162 | ```
163 | 
164 | We can use the `reachState` method as well, to reach an specific state no matter
165 | the name of the transition. The result should be the same as the last example.
166 | 
167 | ``` php
168 | $transition = $machine->reachState('new', 'paid');
169 | ```
170 | 
171 | Because using a machine is a transactional action, all errors will be notified
172 | with Exceptions. In that case, because we can not `ship` an `new` order, we
173 | would receive a `TransitionNotAccessibleException` exception.
174 | 
175 | ``` php
176 | $transition = $machine->transition('new', 'ship');
177 | ```
178 | 
179 | ## Machine Manager
180 | 
181 | To make things easier and to provide a nice interface for the final user, a
182 | `MachineManager` object is created. This object provide as well a nice interface
183 | to dispatch events using the Symfony Event Dispatcher Component.
184 | 
185 | Let's see how it works using the previous Machine object. To make it happen, we
186 | must work with implementations of the interface
187 | `\Elcodi\Component\StateTransitionMachine\Entity\Interfaces\StatefulInterface`,
188 | so our `Order` instance is one of these.
189 | 
190 | Every entity implementing this interface, in order to be able to work with an
191 | specific machine, must be initialized once to make sure that the first state is
192 | already injected. Once this object is initialized, this action is not required
193 | anymore.
194 | 
195 | ``` php
196 | $stateLineFactory = new StateLineFactory();
197 | $eventDispatcher = new EventDispatcher();
198 | $machineManager = new MachineManager(
199 |     $machine,
200 |     $eventDispatcher,
201 |     $stateLineFactory,
202 | );
203 | 
204 | $order = new Order();
205 | $machineManager->initialize($order, 'First state');
206 | $transition = $machineManager->reachState($order, 'paid', 'The order have been
207 | paid');
208 | ```
209 | 
210 | Because the point of entry state is `new` and we can reach the State `paid`,
211 | this transition will be valid.
212 | In this action, several events will be dispatched from the $eventDispatched
213 | instance.
214 | 


--------------------------------------------------------------------------------
/manuscript/component/template.md:
--------------------------------------------------------------------------------
1 | # Template
2 | 
3 | Create, install and manage several templates in your Bamboo installation.
4 | 
5 | * [Component Repository](https://github.com/elcodi/Template)
6 | * [Bundle Repository](https://github.com/elcodi/TemplateBundle)


--------------------------------------------------------------------------------
/manuscript/cookbook/adapters/currency-rates-populator.md:
--------------------------------------------------------------------------------
  1 | # How to add a new Currency Rates Populator adapter
  2 | 
  3 | Bamboo works with several currencies at the same time. This happens when your
  4 | shop work with different countries.
  5 | 
  6 | ## Scenario
  7 | 
  8 | Because you have several currencies, but all products are defined using one
  9 | currency, you need to know the equivalence value between them all.
 10 | 
 11 | The point is that there are a lot of services that provide this information, and
 12 | maybe you want to use one specific, non implemented yet or even your own
 13 | currency rates server.
 14 | 
 15 | ## Solution
 16 | 
 17 | You can create a new adapter for Currency Rates populator. By default, Elcodi
 18 | implementation works with the Yahoo Finance provider. This adapter can be easily
 19 | replaced by creating a new class implementing 
 20 | `CurrencyExchangeRatesProviderAdapterInterface`.
 21 | 
 22 | ``` php
 23 | namespace Elcodi\Component\Currency\Adapter\CurrencyExchangeRatesProvider\Interfaces;
 24 | 
 25 | /**
 26 |  * Interface CurrencyExchangeRatesProviderAdapterInterface
 27 |  */
 28 | interface CurrencyExchangeRatesProviderAdapterInterface
 29 | {
 30 |     /**
 31 |      * Get the latest exchange rates.
 32 |      *
 33 |      * This method will take in account always that the base currency is USD,
 34 |      * and the result must complain this format.
 35 |      *
 36 |      * [
 37 |      *      "EUR" => "1,78342784",
 38 |      *      "YEN" => "0,67438268",
 39 |      *      ...
 40 |      * ]
 41 |      *
 42 |      * @return array exchange rates
 43 |      */
 44 |     public function getExchangeRates();
 45 | }
 46 | ```
 47 | 
 48 | Then, you need to define your class as a service.
 49 | 
 50 | ``` yml
 51 | services:
 52 | 
 53 |     #
 54 |     # My currency rates adapter
 55 |     #
 56 |     my_currency_rates_adapter:
 57 |         class: My\Currency\Rates\Adapter
 58 | ```
 59 | 
 60 | And finally you need to expose your adapter implementation as the used by the 
 61 | framework when loading your currency rates. You can do that by configuring the
 62 | CurrencyBundle and setting your new service id.
 63 | 
 64 | ``` yml
 65 | elcodi_currency:
 66 |     rates_provider:
 67 |         client: my_currency_rates_adapter
 68 | ```
 69 | 
 70 | Now you can use your new implementation by populating your currencies through
 71 | the command line.
 72 | 
 73 | ``` bash
 74 | $ php app/console elcodi:exchangerates:populate
 75 | ```
 76 | 
 77 | ## Used Adapter
 78 | 
 79 | The adapter used by the Dependency Injection is the one aliased with the name
 80 | `elcodi.currency_exchange_rate_adapter`.
 81 | 
 82 | If you want to change the adapter, the only thing you must do is overwrite the
 83 | Currency Bundle configuration in your project, by adding this in your
 84 | `/app/config/config_local.yml` file.
 85 | 
 86 | ``` yaml
 87 | elcodi_currency:
 88 |     rates_provider:
 89 |         adapter: elcodi.currency_exchange_rate_adapter.yahoo_finances
 90 | ```
 91 | 
 92 | ## Adapters
 93 | 
 94 | These are our adapters included in the Core of the application. If you have 
 95 | implemented another adapter and you think that can be interesting to share it,
 96 | then you can create a pull request with your work. We will appreciate it.
 97 | 
 98 | ### Yahoo Finances Adapter
 99 | 
100 | * Namespace - Elcodi\Component\Currency\Adapter\CurrencyExchangeRatesProvider\YahooFinanceProviderAdapter
101 | * DI name - `elcodi.currency_exchange_rate_adapter.yahoo_finances`
102 | 
103 | This extension doesn't need any extra installation
104 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/adapters/image-resize.md:
--------------------------------------------------------------------------------
  1 | # How to add a new Image Resize adapter
  2 | 
  3 | Elcodi is served with a simple but very useful built-in image server. One of
  4 | the most important actions this server is intended for is resizing images.
  5 | 
  6 | ## Scenario
  7 | 
  8 | You need your application to be deployed to a server with PHP GD, but you want
  9 | to use another image resize engine, for example an external API.
 10 | 
 11 | Elcodi provides you a set of limited adapters for image resizing, so we should
 12 | implement this new adapter. Elcodi provides you a simple, fast and amazing way
 13 | to do it without many pain
 14 | 
 15 | ## Solution
 16 | 
 17 | You can create your own image resize engine by adding a new adapter. By default,
 18 | Elcodi is built with an implementation using the PHP GD Extension (you will
 19 | probably find this extension already installed with your regular PHP
 20 | distribution). This adapter can be easily replaced by creating a new class
 21 | implementing `CurrencyExchangeRatesProviderAdapterInterface`.
 22 | 
 23 | ``` php
 24 | <?php
 25 | 
 26 | namespace Elcodi\Component\Media\Adapter\Resizer\Interfaces;
 27 | 
 28 | use Elcodi\Component\Media\ElcodiMediaImageResizeTypes;
 29 | 
 30 | /**
 31 |  * Interface ResizerAdapterInterface
 32 |  */
 33 | interface ResizeAdapterInterface
 34 | {
 35 |     /**
 36 |      * Interface for resize implementations
 37 |      *
 38 |      * @param string  $imageData Image Data
 39 |      * @param integer $height    Height value
 40 |      * @param integer $width     Width value
 41 |      * @param integer $type      Type
 42 |      *
 43 |      * @return string Resized image data
 44 |      */
 45 |     public function resize(
 46 |         $imageData,
 47 |         $height,
 48 |         $width,
 49 |         $type = ElcodiMediaImageResizeTypes::FORCE_MEASURES
 50 |     );
 51 | }
 52 | ```
 53 | 
 54 | Then, you need to define your class as a service.
 55 | 
 56 | ``` yml
 57 | services:
 58 | 
 59 |     #
 60 |     # My image resizer adapter
 61 |     #
 62 |     my_image_resizer_adapter:
 63 |         class: My\Image\Resizer\Adapter
 64 | ```
 65 | 
 66 | And finally you need to expose your adapter implementation as the used by the
 67 | framework when resizing an existing image. You can do that by configuring the
 68 | MediaBundle and setting your new service id.
 69 | 
 70 | ``` yml
 71 | elcodi_media:
 72 |     images:
 73 |         resize:
 74 |             client: my_image_resizer_adapter
 75 | ```
 76 | 
 77 | Now, everytime an image needs to be resized, you will see your new adapter in
 78 | action.
 79 | 
 80 | ## Resize types
 81 | 
 82 | Elcodi resize adapter must complain 6 different resize types. Each type is
 83 | defined using the constants placed in `ElcodiMediaImageResizeTypes`.
 84 | 
 85 | ``` php
 86 | namespace Elcodi\Component\Media;
 87 | 
 88 | /**
 89 |  * Class ElcodiMediaImageResizeTypes
 90 |  */
 91 | final class ElcodiMediaImageResizeTypes
 92 | {
 93 |     /**
 94 |      * @var integer
 95 |      *
 96 |      * Do not resize the image
 97 |      */
 98 |     const NO_RESIZE = 0;
 99 | 
100 |     /**
101 |      * @var integer
102 |      *
103 |      * Resize mode FORCE_MEASURES sets the image to the desired size.
104 |      * DOES NOT preserve original aspect ratio.
105 |      * Best for fixed size images like banners
106 |      */
107 |     const FORCE_MEASURES = 1;
108 | 
109 |     /**
110 |      * @var integer
111 |      *
112 |      * Resize mode INSET sets the image to the desired size.
113 |      * Preserves original aspect ratio so it might not fill the box.
114 |      * Best for large thumbnails
115 |      */
116 |     const INSET = 2;
117 | 
118 |     /**
119 |      * @var integer
120 |      *
121 |      * Resize mode INSET_FILL_WHITE sets the image to the desired size.
122 |      * Preserves original aspect ratio and adds white color to the background in order to fill the box.
123 |      * Best for small thumbnails
124 |      */
125 |     const INSET_FILL_WHITE = 3;
126 | 
127 |     /**
128 |      * @var integer
129 |      *
130 |      * Outbound resizing
131 |      */
132 |     const OUTBOUNDS_FILL_WHITE = 4;
133 | 
134 |     /**
135 |      * @var integer
136 |      *
137 |      * Resize mode 5 sets the image to the desired size.
138 |      * Preserves original aspect ratio and crops image for only get this area.
139 |      */
140 |     const OUTBOUND_CROP = 5;
141 | }
142 | ```
143 | 
144 | As you can see in the adapter interface, by default this resize must force
145 | measures.
146 | 
147 | ## Used Adapter
148 | 
149 | The adapter used by the Dependency Injection is the one aliased with the name
150 | `elcodi.media_resize_adapter`.
151 | 
152 | If you want to change the adapter, the only thing you must do is overwrite the
153 | Media Bundle configuration in your project, by adding this in your
154 | `/app/config/config_local.yml` file.
155 | 
156 | ``` yaml
157 | elcodi_media:
158 |     image:
159 |         resize:
160 |             adapter: elcodi.media_resize_adapter.gd
161 | ```
162 | 
163 | ## Adapters
164 | 
165 | These are our adapters included in the Core of the application. If you have
166 | implemented another adapter and you think that can be interesting to share it,
167 | then you can create a pull request with your work. We will appreciate it.
168 | 
169 | ### GD Extension Adapter
170 | 
171 | * Namespace - Elcodi\Component\Media\Adapter\Resizer\GDResizeAdapter
172 | * DI name - `elcodi.media_resize_adapter.gd`
173 | 
174 | This extension doesn't need any extra installation
175 | 
176 | ### Imagemagick Adapter
177 | 
178 | * Namespace - Elcodi\Component\Media\Adapter\Resizer\ImageMagickResizeAdapter
179 | * DI name - `elcodi.media_resize_adapter.imagemagick`
180 | 
181 | For more info just visit their [installation page](http://php.net/manual/en/imagick.setup.php)
182 | 
183 | > On the installation step you will be asked to provide the Imagick installation
184 | > path. Ensure to configure the parameter imagick_convert_bin_path right
185 | 
186 | This adapter may need some configuration. This is the reference. Feel free to
187 | overwrite these values in your project.
188 | 
189 | ``` yaml
190 | elcodi_media:
191 |     image:
192 |         resize:
193 |             converter_bin_path: /usr/bin/convert
194 |             converter_default_profile: /usr/share/color/icc/colord/sRGB.icc
195 | ```
196 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/adapters/location-loader.md:
--------------------------------------------------------------------------------
 1 | # How to add a new Location Loader adapter
 2 | 
 3 | Elcodi uses by default the Github implementaton, retrieving data from some a
 4 | Github repository.
 5 | 
 6 | ## Scenario
 7 | 
 8 | You are using another implementation for Locations. This means that your
 9 | database structure is not the same as Elcodi proposes. Then, if you still want
10 | to use this feature for fast location loading, then you must implement your own
11 | loader adapter.
12 | 
13 | ## Solution
14 | 
15 | For your own adapter implementation you only need to know where your actual data
16 | is stored. The adapter itself is only a class that implements interface
17 | `Elcodi\Component\Geo\Adapter\LocationLoader\GithubLocationLoaderAdapter`.
18 | 
19 | ``` php
20 | namespace Elcodi\Component\Geo\Adapter\LocationLoader\Interfaces;
21 | 
22 | /**
23 |  * Interface LocationLoaderAdapterInterface
24 |  */
25 | interface LocationLoaderAdapterInterface
26 | {
27 |     /**
28 |      * Given a country name, return the sql to be loaded
29 |      *
30 |      * @param string $countryName Country name
31 |      *
32 |      * @return string Sql to be loaded
33 |      */
34 |     public function getSqlForCountry($countryName);
35 | }
36 | ```
37 | 
38 | ## Used Adapter
39 | 
40 | The adapter used by the Dependency Injection is the one aliased with the name
41 | `elcodi.location_loader`.
42 | 
43 | If you want to change the adapter, the only thing you must do is overwrite the
44 | Geo Bundle configuration in your project, by adding this in your
45 | `/app/config/config_local.yml` file.
46 | 
47 | ``` yaml
48 | elcodi_geo:
49 |     location:
50 |         loader_adapter: elcodi.location_loader_adapter.github
51 | ```
52 | 
53 | ## Adapters
54 | 
55 | These are our adapters included in the Core of the application. If you have
56 | implemented another adapter and you think that can be interesting to share it,
57 | then you can create a pull request with your work. We will appreciate it.
58 | 
59 | ### Github Loader Adapter
60 | 
61 | Uses Github repository
62 | [elcodi/LocationDumps](https://github.com/elcodi/LocationDumps), and actually
63 | only some countries have been pre-generated.
64 | 
65 | * Namespace - Elcodi\Component\Geo\Adapter\LocationLoader\GithubLocationLoaderAdapter
66 | * DI name - `elcodi.location_loader_adapter.github`
67 | 
68 | Countries generated:
69 | * [Andorra - AD](https://raw.githubusercontent.com/elcodi/LocationDumps/master/AD.sql)
70 | * [Austria - AT](https://raw.githubusercontent.com/elcodi/LocationDumps/master/AT.sql)
71 | * [Belgium - BE](https://raw.githubusercontent.com/elcodi/LocationDumps/master/BE.sql)
72 | * [Switzerland - CH](https://raw.githubusercontent.com/elcodi/LocationDumps/master/CH.sql)
73 | * [Germany - AD](https://raw.githubusercontent.com/elcodi/LocationDumps/master/DE.sql)
74 | * [Denmark - DK](https://raw.githubusercontent.com/elcodi/LocationDumps/master/DK.sql)
75 | * [Spain - ES](https://raw.githubusercontent.com/elcodi/LocationDumps/master/ES.sql)
76 | * [Finland - FI](https://raw.githubusercontent.com/elcodi/LocationDumps/master/FI.sql)
77 | * [France - FR](https://raw.githubusercontent.com/elcodi/LocationDumps/master/FR.sql)
78 | * [United Kingdom - GB](https://raw.githubusercontent.com/elcodi/LocationDumps/master/GB.sql)
79 | * [Italy - IT](https://raw.githubusercontent.com/elcodi/LocationDumps/master/IT.sql)
80 | * [Poland - PL](https://raw.githubusercontent.com/elcodi/LocationDumps/master/PL.sql)
81 | 
82 | If you generate your country and is not in this list or is not updated, then
83 | don't hesitate to create a PR and ping us
84 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/adapters/location-populator.md:
--------------------------------------------------------------------------------
 1 | # How to add a new Location Populator adapter
 2 | 
 3 | By default Elcodi uses an external website called
 4 | [Geonames](http://www.geonames.org/). This website proposes some data files with
 5 | country location references. This data is treated, organized and inserted as
 6 | entities in our Doctrine infrastructure.
 7 | 
 8 | This adapter just takes this data from that service and populates that country.
 9 | 
10 | ## Scenario
11 | 
12 | You have your own location server, for example, a non-free service that proposes
13 | you this structure in a more precise way.
14 | 
15 | ## Solution
16 | 
17 | You can create your own adapter for that. You just need to implement a simple
18 | Interface, with one single method. That easy.
19 | 
20 | ``` php
21 | namespace Elcodi\Component\Geo\Adapter\LocationPopulator\Interfaces;
22 | 
23 | use Elcodi\Component\Geo\Entity\Interfaces\LocationInterface;
24 | 
25 | /**
26 |  * Interface PopulatorInterface
27 |  */
28 | interface LocationPopulatorAdapterInterface
29 | {
30 |     /**
31 |      * Populate a country
32 |      *
33 |      * @param string $countryCode Country Code
34 |      *
35 |      * @return LocationInterface Root location
36 |      */
37 |     public function populate($countryCode);
38 | }
39 | ```
40 | 
41 | ## Used Adapter
42 | 
43 | The adapter used by the Dependency Injection is the one aliased with the name
44 | `elcodi.location_populator`.
45 | 
46 | If you want to change the adapter, the only thing you must do is overwrite the
47 | Geo Bundle configuration in your project, by adding this in your
48 | `/app/config/config_local.yml` file.
49 | 
50 | ``` yaml
51 | elcodi_geo:
52 |     location:
53 |         populator_adapter: elcodi.location_populator_adapter.geonames
54 | ```
55 | 
56 | ## Adapters
57 | 
58 | These are our adapters included in the Core of the application. If you have
59 | implemented another adapter and you think that can be interesting to share it,
60 | then you can create a pull request with your work. We will appreciate it.
61 | 
62 | ### Geonames Populator Adapter
63 | 
64 | * Namespace - Elcodi\Component\Geo\Adapter\LocationPopulator\GeonamesLocationPopulatorAdapter
65 | * DI name - `elcodi.location_populator_adapter.geonames`
66 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/adapters/location-provider.md:
--------------------------------------------------------------------------------
  1 | # How to add a new Location Provider adapter
  2 | 
  3 | One of the most important parts in an Ecommerce is the way Locations and all
  4 | Geo information is treated. In order to simplify the way Elcodi offers this
  5 | feature, you will be able to work with a nice Location structure using two
  6 | different accessing approaches.
  7 | 
  8 | ## Scenario
  9 | 
 10 | Your Location structure has changed, or the way you access to the data. Maybe
 11 | this scenario is not common at all, because Elcodi covers the most important and
 12 | used ways of accessing, but you have your own particular way.
 13 | 
 14 | ## Solution
 15 | 
 16 | Implementing an interface is the way you will be able to expose your way and not
 17 | breaking any external implementation. You'll see that implementable interface
 18 | offers some accessible methods, all of them specified properly in order to make
 19 | implementation easy to understand. This interface as well uses complex value
 20 | objects, so there's no margin of error there.
 21 | 
 22 | ``` php
 23 | namespace Elcodi\Component\Geo\Adapter\LocationProvider\Interfaces;
 24 | 
 25 | use Elcodi\Component\Geo\ValueObject\LocationData;
 26 | 
 27 | /**
 28 |  * Interface LocationProviderAdapterInterface
 29 |  */
 30 | interface LocationProviderAdapterInterface
 31 | {
 32 |     /**
 33 |      * Get all the root locations.
 34 |      *
 35 |      * @return LocationData[] Collection of locations
 36 |      */
 37 |     public function getRootLocations();
 38 | 
 39 |     /**
 40 |      * Get the children given a location id.
 41 |      *
 42 |      * @param string $id The location Id.
 43 |      *
 44 |      * @return LocationData[] Collection of locations
 45 |      */
 46 |     public function getChildren($id);
 47 | 
 48 |     /**
 49 |      * Get the parents given a location id.
 50 |      *
 51 |      * @param string $id The location Id.
 52 |      *
 53 |      * @return LocationData[] Collection of locations
 54 |      */
 55 |     public function getParents($id);
 56 | 
 57 |     /**
 58 |      * Get the full location info given it's id.
 59 |      *
 60 |      * @param string $id The location id.
 61 |      *
 62 |      * @return LocationData Location info
 63 |      */
 64 |     public function getLocation($id);
 65 | 
 66 |     /**
 67 |      * Get the hierarchy given a location sorted from root to the given
 68 |      * location.
 69 |      *
 70 |      * @param string $id The location id.
 71 |      *
 72 |      * @return LocationData[] Collection of locations
 73 |      */
 74 |     public function getHierarchy($id);
 75 | 
 76 |     /**
 77 |      * Checks if the first received id is contained between the rest of ids
 78 |      * received as second parameter
 79 |      *
 80 |      * @param string $id  The location Id
 81 |      * @param array  $ids The location Ids
 82 |      *
 83 |      * @return boolean Location is container
 84 |      */
 85 |     public function in($id, array $ids);
 86 | }
 87 | ```
 88 | 
 89 | ## Used Adapter
 90 | 
 91 | The adapter used by the Dependency Injection is the one aliased with the name
 92 | `elcodi.location_provider`.
 93 | 
 94 | If you want to change the adapter, the only thing you must do is overwrite the
 95 | Geo Bundle configuration in your project, by adding this in your
 96 | `/app/config/config_local.yml` file.
 97 | 
 98 | ``` yaml
 99 | elcodi_geo:
100 |     location:
101 |         provider_adapter: elcodi.location_provider_adapter.service
102 | ```
103 | 
104 | ## Adapters
105 | 
106 | These are our adapters included in the Core of the application. If you have
107 | implemented another adapter and you think that can be interesting to share it,
108 | then you can create a pull request with your work. We will appreciate it.
109 | 
110 | ### Service Provider Adapter
111 | 
112 | This adapter uses a single service to make calls. This is useful for centralized
113 | systems. Easy and simple.
114 | 
115 | * Namespace - Elcodi\Component\Geo\Adapter\LocationProvider\LocationServiceProviderAdapter
116 | * DI name - `lcodi.location_provider_adapter.service`
117 | 
118 | ### API Provider Adapter
119 | 
120 | This adapter offers the same data but using a simple API infrastructure. This is
121 | useful, for example, if you work with several projects at the same time, so you
122 | only need one location database, shared by all websites.
123 | 
124 | * Namespace - Elcodi\Component\Geo\Adapter\LocationProvider\LocationApiProviderAdapter
125 | * DI name - `lcodi.location_provider_adapter.api`
126 | 
127 | You can actually use an external location host. By default, this value is null,
128 | so make sure you define properly this value in your
129 | `/app/config/config_local.yml` file.
130 | 
131 | ``` yaml
132 | elcodi_geo:
133 |     location:
134 |         api_host: ~
135 | ```
136 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/adapters/metric-bucket.md:
--------------------------------------------------------------------------------
  1 | # How to add a new Metric Bucket adapter¡
  2 | 
  3 | By default, Elcodi provides one Metric Bucket implementation, based on Redis.
  4 | You can read more information about this in the
  5 | [Book Metrics Chapter](http://elcodi.io/docs/component/metrics/). This feature has been implemented
  6 | using Adapters as well, so you could implement your own.
  7 | 
  8 | ## Scenario
  9 | 
 10 | You have your store installed in third party environment. Bad news... Redis is
 11 | not installed and you cannot install it even if you want it. This scenario is
 12 | very common, so you should be able to use Metrics as well, even without Redis.
 13 | 
 14 | ## Solution
 15 | 
 16 | Well, first of all you should think about where to place your metric cache. A
 17 | bucket is nothing but a cache layer for your metrics. Each metric entry is a
 18 | database entry as well, but because only working with Doctrine would be so hard
 19 | for your server and user, we work with a cache layer.
 20 | 
 21 | This cache implementation should be able to build results in a very fast way, so
 22 | this is the reason why default implementation uses Redis.
 23 | 
 24 | ## AbstractMetricsBucket
 25 | 
 26 | Like every other adapters implementations, there is an Interface for that.
 27 | Remember that an abstract class can work as an interface as well if you define
 28 | methods as abstract.
 29 | 
 30 | AbstractMetricsBucket is your class if you want to create a new adapter for
 31 | that.
 32 | 
 33 | ``` php
 34 | namespace Elcodi\Component\Metric\Core\Bucket\Abstracts;
 35 | 
 36 | use Elcodi\Component\Metric\Core\Entity\Interfaces\EntryInterface;
 37 | 
 38 | /**
 39 |  * Class AbstractMetricsBucket
 40 |  */
 41 | abstract class AbstractMetricsBucket
 42 | {
 43 |     /**
 44 |      * Add Metric into Bucket
 45 |      *
 46 |      * @param EntryInterface $entry Entry
 47 |      *
 48 |      * @return $this Self Object
 49 |      */
 50 |     abstract public function add(EntryInterface $entry);
 51 | 
 52 |     /**
 53 |      * Get number of unique beacons given an event and a set of dates
 54 |      *
 55 |      * @param string $token Event
 56 |      * @param string $event Token
 57 |      * @param array  $dates Dates
 58 |      *
 59 |      * @return integer Number of hits
 60 |      */
 61 |     abstract public function getBeaconsUnique($token, $event, array $dates);
 62 | 
 63 |     /**
 64 |      * Get the total of beacons given an event and a set of dates
 65 |      *
 66 |      * @param string $token Event
 67 |      * @param string $event Token
 68 |      * @param array  $dates Dates
 69 |      *
 70 |      * @return integer Number of beacons, given an event and dates
 71 |      */
 72 |     abstract public function getBeaconsTotal($token, $event, array $dates);
 73 | 
 74 |     /**
 75 |      * Get distributions given an event and a set of dates
 76 |      *
 77 |      * @param string $token Event
 78 |      * @param string $event Token
 79 |      * @param array  $dates Dates
 80 |      *
 81 |      * @return integer Accumulation of event and given dates
 82 |      */
 83 |     abstract public function getAccumulation($token, $event, array $dates);
 84 | 
 85 |     /**
 86 |      * Get distributions given an event and a set of dates
 87 |      *
 88 |      * [
 89 |      *      "value3": 24,
 90 |      *      "value7": 13,
 91 |      *      "value8": 9,
 92 |      * ]
 93 |      *
 94 |      * @param string $token Event
 95 |      * @param string $event Token
 96 |      * @param array  $dates Dates
 97 |      *
 98 |      * @return array Distribution with totals
 99 |      */
100 |     abstract public function getDistributions($token, $event, array $dates);
101 | }
102 | ```
103 | 
104 | This class provides you some helpers as well, related to how cache keys should
105 | be built in order to avoid collisions inside the bucket
106 | 
107 | ``` php
108 | /**
109 |  * Create key given an entry
110 |  *
111 |  * @param string $token Event
112 |  * @param string $event Token
113 |  * @param string $date  Date
114 |  *
115 |  * @return string key
116 |  */
117 | protected function generateEntryKey($token, $event, $date)
118 | {
119 |     return
120 |         $this->normalizeForKey($token) .
121 |         '.' .
122 |         $this->normalizeForKey($event) .
123 |         '.' .
124 |         $this->normalizeForKey($date);
125 | }
126 | 
127 | /**
128 |  * Normalize string for key format
129 |  *
130 |  * @param string $string String
131 |  *
132 |  * @return string String normalized
133 |  */
134 | public function normalizeForKey($string)
135 | {
136 |     return str_replace('.', '_', $string);
137 | }
138 | ```
139 | 
140 | ## Used Adapter
141 | 
142 | The adapter used by the Dependency Injection is the one aliased with the name
143 | `elcodi.metrics_bucket`.
144 | 
145 | If you want to change the adapter, the only thing you must do is overwrite the
146 | Metric Bundle configuration in your project, by adding this in your
147 | `/app/config/config_local.yml` file.
148 | 
149 | ``` yaml
150 | elcodi_metric:
151 |     bucket:
152 |         client: elcodi.redis_metrics_bucket
153 | ```
154 | 
155 | ## Adapters
156 | 
157 | These are our adapters included in the Core of the application. If you have
158 | implemented another adapter and you think that can be interesting to share it,
159 | then you can create a pull request with your work. We will appreciate it.
160 | 
161 | ### Redis Bucket Adapter
162 | 
163 | * Namespace - Elcodi\Component\Metric\Core\Bucket\RedisMetricsBucket
164 | * DI name - `elcodi.redis_metrics_bucket`
165 | 
166 | This extension doesn't need any extra installation. If redis-server is not
167 | installed, then nothing happens. If it is, then will work properly.
168 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/adapters/related-purchasables-provider.md:
--------------------------------------------------------------------------------
 1 | # How to add a new Related Products Provider adapter
 2 | 
 3 | In some pages, specially all related to a purchasable object, you may show some
 4 | related purchasable objects as well. This features is very used in all websites
 5 | to increase the valuable relation between final pages in the same website.
 6 | 
 7 | ## Scenario
 8 | 
 9 | Elcodi offers a simple implementation of how these purchasable objects should be
10 | found, taking the principal category as the common element between them all. The
11 | main thing here is that maybe you work with external implementations or services
12 | that makes this task.
13 | 
14 | ## Solution
15 | 
16 | Again, create your own adapter for that. Elcodi provides an interface for all
17 | external implementations (our implementation uses this interface as well).
18 | 
19 | ``` php
20 | namespace Elcodi\Component\Product\Adapter\SimilarPurchasablesProvider\Interfaces;
21 | 
22 | use Elcodi\Component\Product\Entity\Interfaces\PurchasableInterface;
23 | 
24 | /**
25 |  * Interface RelatedPurchasablesProviderInterface
26 |  */
27 | interface RelatedPurchasablesProviderInterface
28 | {
29 |     /**
30 |      * Given a Purchasable, return a collection of related purchasables.
31 |      *
32 |      * @param PurchasableInterface $purchasable Purchasable
33 |      * @param int                  $limit       Limit of elements retrieved
34 |      *
35 |      * @return array Related products
36 |      */
37 |     public function getRelatedPurchasables(PurchasableInterface $purchasable, $limit);
38 | 
39 |     /**
40 |      * Given a Collection of Purchasables, return a collection of related
41 |      * purchasables.
42 |      *
43 |      * @param PurchasableInterface[] $purchasables Purchasable
44 |      * @param int                    $limit        Limit of elements retrieved
45 |      *
46 |      * @return array Related products
47 |      */
48 |     public function getRelatedPurchasablesFromArray(array $purchasables, $limit);
49 | }
50 | ```
51 | 
52 | As you can see, all adapters must implement two methods. This is because
53 | sometimes both methods require different implementations. Anyway, most
54 | implementations will have common logic shared by both methods.
55 | 
56 | ## Used Adapter
57 | 
58 | The adapter used by the Dependency Injection is the one aliased with the name
59 | `elcodi.related_purchasables_provider`.
60 | 
61 | If you want to change the adapter, the only thing you must do is overwrite the
62 | Product Bundle configuration in your project, by adding this in your
63 | `/app/config/config_local.yml` file.
64 | 
65 | ``` yaml
66 | elcodi_product:
67 |     related_purchasables_provider:
68 |         adapter: elcodi.related_purchasables_provider.same_category
69 | ```
70 | 
71 | ## Adapters
72 | 
73 | These are our adapters included in the Core of the application. If you have
74 | implemented another adapter and you think that can be interesting to share it,
75 | then you can create a pull request with your work. We will appreciate it.
76 | 
77 | ### Same Category Related
78 | 
79 | Takes in account the same principal category of the given Purchasable. If the
80 | object is a Variant, then its Product principal category is used. This
81 | implementation not supports external Purchasable implementations.
82 | 
83 | * Namespace - Elcodi\Component\Product\Adapter\SimilarPurchasablesProvider\SameCategoryRelatedPurchasableProvider
84 | * DI name - `elcodi.related_purchasables_provider.same_category`
85 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/deprecation/deprecate-a-method.md:
--------------------------------------------------------------------------------
1 | # How to deprecate a method


--------------------------------------------------------------------------------
/manuscript/cookbook/implementation/implement-a-collector.md:
--------------------------------------------------------------------------------
 1 | # How to Implement a Collector
 2 | 
 3 | If you look for how to create a simple Collector by using components provided by
 4 | Symfony, you will find nothing. This guide will show you some light about how to
 5 | do it using existing Symfony code.
 6 | 
 7 | Please, read that article from [Marc Morera](http://mmoreram.com) called
 8 | [EventListeners as Collectors in Symfony](http://mmoreram.com/blog/2015/08/28/eventlisteners-as-collectors-in-symfony/)
 9 | that talks about how to implement a simple collector by using the Event 
10 | Dispatcher symfony component.


--------------------------------------------------------------------------------
/manuscript/cookbook/implementation/implement-a-controller-and-a-command.md:
--------------------------------------------------------------------------------
  1 | # How to Implement a Controller or a Command
  2 | 
  3 | Controllers and Commands in Elcodi are exactly the same than Controllers and 
  4 | Commands in Symfony. No difference between them. But in Elcodi we have a strong
  5 | philosophy about how to create them in order to be valid or usable in the Open
  6 | Source environment.
  7 | 
  8 | ## Scenario
  9 | 
 10 | We have a Bamboo-based application in our server and we need to create a new 
 11 | entry-point for our application, for example a new Controller to manage orders
 12 | from specific users, in order to create special newsletters and increase the
 13 | number of orders per customer.
 14 | 
 15 | Controllers and Commands are designed and implemented following a simple but
 16 | specific way. We need to know how both classes are created in Elcodi in order to
 17 | follow the same philosophy in all places.
 18 | 
 19 | ## Solution
 20 | 
 21 | Following this specific way, we need to know the differences between creating
 22 | Controllers and Commands as services, or simply rely to the framework the way
 23 | these classes are auto-discovered.
 24 | 
 25 | ### Services in Elcodi
 26 | 
 27 | All Elcodi Controllers and Commands are defined as services. This is because we
 28 | are *Overwriting Oriented Programming* and we have in mind that every single
 29 | implementation sensible to be changed between projects must be easily 
 30 | customized.
 31 | 
 32 | In Symfony, and because Dependency Injection definition has a very well documented
 33 | overwriting strategy, we have decided that everything must be defined as a 
 34 | service.
 35 | 
 36 | We have a convention about how a Controller and a Command must be registered in
 37 | your DI container
 38 | 
 39 | ``` yaml
 40 | elcodi.controller.image_upload
 41 | elcodi.command.populate_currency_rates
 42 | ```
 43 | 
 44 | Of course, and because it should only depend on the Symfony Components, but never
 45 | the Symfony Framework nor the FrameworkBundle, both implementations must not extend
 46 | Framework classes.
 47 | 
 48 | ### Framework Controllers in Bamboo
 49 | 
 50 | When you work in Bamboo (or in your project on top of Elcodi Components and 
 51 | Bundles) we don't recommend the usage of Controllers and Commands as services.
 52 | We think that both implementations are Entry Points and should be Framework
 53 | related.
 54 | 
 55 | This means that your Controllers or Commands should never have business logic,
 56 | and should place all this logic in your service layer.
 57 | 
 58 | Having said that, we recommend the usage of *FrameworkBundle* Controller class to
 59 | endow your controllers with easy access to the DI container and a good set of
 60 | pre-built methods.
 61 | 
 62 | ``` php
 63 | use Symfony\Bundle\FrameworkBundle\Controller\Controller;
 64 | 
 65 | /**
 66 |  * Cart controllers
 67 |  */
 68 | class CartController extends Controller
 69 | {
 70 | }
 71 | ```
 72 | 
 73 | ### Framework Commands in Bamboo
 74 | 
 75 | We have the same opinion for Commands and Controllers.
 76 | 
 77 | ``` php
 78 | use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;
 79 | 
 80 | /**
 81 |  * Cart controllers
 82 |  */
 83 | class MyCommand extends ContainerAwareCommand
 84 | {
 85 | }
 86 | ```
 87 | 
 88 | ### Annotations in Bamboo Controllers
 89 | 
 90 | In Bamboo, we use annotations in all our controllers in order to make the code more
 91 | understandable and to focus only on business logic. Annotations solve
 92 | repetitive things and should be perfectly documented.
 93 | 
 94 | > Magic? Yes, of course, same magic than yml readers, than Container
 95 | > compilation, than service builds... so what?
 96 | 
 97 | For this reason, we are using 
 98 | [ControllerExtraBundle](http://github.com/mmoreram/ControllerExtraBundle) and
 99 | [SensioFrameworkExtraBundle](https://github.com/sensiolabs/SensioFrameworkExtraBundle).
100 | 
101 | Let's see an example.
102 | 
103 | ``` php
104 | use Mmoreram\ControllerExtraBundle\Annotation\Entity as AnnotationEntity;
105 | use Mmoreram\ControllerExtraBundle\Annotation\Form as AnnotationForm;
106 | use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
107 | use Symfony\Bundle\FrameworkBundle\Controller\Controller;
108 | 
109 | /**
110 |  * Cart controllers
111 |  *
112 |  * @Route(
113 |  *      path = "/cart",
114 |  * )
115 |  */
116 | class CartController extends Controller
117 | {
118 |     /**
119 |      * Cart view
120 |      *
121 |      * @param FormView      $formView Form view
122 |      * @param CartInterface $cart     Cart
123 |      *
124 |      * @return Response Response
125 |      *
126 |      * @Route(
127 |      *      path = "",
128 |      *      name = "store_cart_view",
129 |      *      methods = {"GET"}
130 |      * )
131 |      *
132 |      * @AnnotationEntity(
133 |      *      class = {
134 |      *          "factory" = "elcodi.wrapper.cart",
135 |      *          "method" = "loadCart",
136 |      *          "static" = false,
137 |      *      },
138 |      *      name = "cart"
139 |      * )
140 |      * @AnnotationForm(
141 |      *      class = "store_cart_form_type_cart",
142 |      *      name  = "formView",
143 |      *      entity = "cart",
144 |      * )
145 |      */
146 |     public function viewAction(
147 |         FormView $formView,
148 |         CartInterface $cart
149 |     ) {
150 |         // ...
151 |     
152 |         return $this->renderTemplate(
153 |             'Pages:cart-view.html.twig',
154 |             [
155 |                 // ...
156 |             ]
157 |         );
158 |     }
159 | }
160 | ```
161 | 
162 | You can find some documentation of both annotation packages
163 | 
164 | * [ControllerExtraBundle](https://github.com/mmoreram/ControllerExtraBundle/blob/master/README.md)
165 | * [SensioFrameworkExtraBundle](http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html)
166 | 
167 | Please, before using annotations in your project make sure that you know how
168 | they work and how to use them. Read the documentation of both packages and try
169 | to understand their meaning.
170 | 
171 | ## Related links
172 | 
173 | * [Symfony docs - How to define controllers as services](http://symfony.com/doc/current/cookbook/controller/service.html)
174 | * [Symfony docs - How to define commands as services](http://symfony.com/doc/current/cookbook/console/commands_as_services.html)


--------------------------------------------------------------------------------
/manuscript/cookbook/implementation/implement-a-factory.md:
--------------------------------------------------------------------------------
  1 | # How to Implement a Factory
  2 | 
  3 | Factories usage is one of the most distinctive things in Elcodi architecture
  4 | style. Every single entity in Elcodi ecosystem is created using its own Factory,
  5 | so by default, an entity should never define its own construction state.
  6 | 
  7 | ## Scenario
  8 | 
  9 | Our project have grown and we have some extra needs. We have created new 
 10 | entities, and because we strongly believe that an entity is not responsible of 
 11 | how it should be created, the factory should holds this responsibility. 
 12 | This means that an entity should never implement the `__construct()` method and 
 13 | it should never initialize any variable.
 14 | 
 15 | In one of our services we need to create a new entity instance. How easy is 
 16 | creating this entity by using `new()`, right? But then, this piece of code is
 17 | not testable anymore, so we should be able to mock this new entity.
 18 | 
 19 | Let's create a new factory for that new entity!
 20 | 
 21 | ## Solution
 22 | 
 23 | A factory is a simple class that, returns a new entity instance once it knows
 24 | how to build it. Because in Elcodi all entity namespaces are defined by a 
 25 | parameter, any factory must use these parameters to create an instance.
 26 | 
 27 | ``` php
 28 | use Elcodi\Component\Language\Entity\Interfaces\LanguageInterface;
 29 | 
 30 | /**
 31 |  * Class LanguageFactory
 32 |  */
 33 | class LanguageFactory extends AbstractFactory
 34 | {
 35 |     /**
 36 |      * @var string
 37 |      *
 38 |      * Entity namespace
 39 |      */
 40 |     protected $entityNamespace;
 41 | 
 42 |     /**
 43 |      * Set Entity Namespace
 44 |      *
 45 |      * @param string $entityNamespace Entity namespace
 46 |      *
 47 |      * @return $this Self object
 48 |      */
 49 |     public function setEntityNamespace($entityNamespace)
 50 |     {
 51 |         $this->entityNamespace = $entityNamespace;
 52 | 
 53 |         return $this;
 54 |     }
 55 | 
 56 |     /**
 57 |      * Creates an instance of a simple language.
 58 |      *
 59 |      * This method must return always an empty instance for related entity
 60 |      *
 61 |      * @return LanguageInterface Empty entity
 62 |      */
 63 |     public function create()
 64 |     {
 65 |         /**
 66 |          * @var LanguageInterface $language
 67 |          */
 68 |         $classNamespace = $this->getEntityNamespace();
 69 |         $language = new $classNamespace();
 70 | 
 71 |         $language->setEnabled(false);
 72 | 
 73 |         return $language;
 74 |     }
 75 | }
 76 | ```
 77 | 
 78 | As you can see, the namespace is injected, and when the factory creates the 
 79 | instance, uses this namespace. With this strategy, the factory becomes uncoupled
 80 | from the entity implementation.
 81 | 
 82 | In order to make things easier, there is a Trait in package `elcodi/core`, 
 83 | designed to be an abstraction of a Factory. Extending abstract class 
 84 | `AbstractFactory` as is shown in examples, you can easily access to 
 85 | `$this->getEntityNamespace()` having the same result as before.
 86 | 
 87 | ``` php
 88 | use Elcodi\Component\Core\Factory\Abstracts\AbstractFactory;
 89 | use Elcodi\Component\Language\Entity\Interfaces\LanguageInterface;
 90 | 
 91 | /**
 92 |  * Class LanguageFactory
 93 |  */
 94 | class LanguageFactory extends AbstractFactory
 95 | {
 96 |     /**
 97 |      * Creates an instance of a simple language.
 98 |      *
 99 |      * This method must return always an empty instance for related entity
100 |      *
101 |      * @return LanguageInterface Empty entity
102 |      */
103 |     public function create()
104 |     {
105 |         /**
106 |          * @var LanguageInterface $language
107 |          */
108 |         $classNamespace = $this->getEntityNamespace();
109 |         $language = new $classNamespace();
110 | 
111 |         $language->setEnabled(false);
112 | 
113 |         return $language;
114 |     }
115 | }
116 | ```
117 | 
118 | ### Factory as a service
119 | 
120 | Because the factory dependencies need to be resolved, we must define the factory
121 | as a service.
122 | 
123 | ``` yaml
124 | services:
125 | 
126 |     #
127 |     # Factory for entity language
128 |     #
129 |     elcodi.factory.language:
130 |         class: %elcodi.factory.language.class%
131 |         calls:
132 |             - [setEntityNamespace, ["%elcodi.entity.language.class%"]]
133 | ```
134 | 
135 | Once this factory is created as a service, you should inject this factory in 
136 | your service in order to using them when new entity instance is required.
137 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/implementation/implement-a-form-type.md:
--------------------------------------------------------------------------------
  1 | # How to Implement a Form Type
  2 | 
  3 | A FormType object in Elcodi ecosystem must follow some rules in order to comply
  4 | with the project flexibility.
  5 | 
  6 | ## Scenario
  7 | 
  8 | We need to manage one of our own new entities. We have created the entity, the
  9 | form and the repository, so we need to create some extra pages in our admin
 10 | panel in order to create, modify and delete them.
 11 | 
 12 | In order to create these new pages, we need some mechanism to create these 
 13 | forms, being able to do it properly and extensible, following the best Symfony 
 14 | and Elcodi standards.
 15 | 
 16 | ## Solution
 17 | 
 18 | As you may know, whenever we want to work with forms in Symfony, best practices 
 19 | say that we should use FormType classes. These classes are meant to be a PHP 
 20 | representation of how a form should be treated and defined.
 21 | 
 22 | So let's use them.
 23 | 
 24 | ### Symfony Forms
 25 | 
 26 | Symfony Forms is not a Elcodi-related implementation, so first of all you should
 27 | know as much as possible about how Symfony Forms works.
 28 | 
 29 | We strongly encourage you to learn about them in their documentation before 
 30 | proceeding with our specific documentation.
 31 | 
 32 | [Symfony Book - Forms](http://symfony.com/doc/current/book/forms.html)
 33 | [Symfony Best Practices - Forms](http://symfony.com/doc/current/best_practices/forms.html)
 34 | 
 35 | ### Using Factories
 36 | 
 37 | Remember that every single entity must be created via its factory in Elcodi
 38 | Bundles. For more information, please see [Factories](http://elcodi.io/docs/cookbook/implementation/implement-a-factory/). 
 39 | In order to use this feature in Symfony Form Types, we must inject always the 
 40 | related entity factory.
 41 | 
 42 | ``` php
 43 | use Elcodi\Component\Core\Factory\Abstracts\AbstractFactory;
 44 | 
 45 | /**
 46 |  * @var AbstractFactory
 47 |  *
 48 |  * Factory
 49 |  */
 50 | protected $factory;
 51 | 
 52 | /**
 53 |  * Sets Factory
 54 |  *
 55 |  * @param AbstractFactory $factory Factory
 56 |  *
 57 |  * @return $this Self object
 58 |  */
 59 | public function setFactory(AbstractFactory $factory)
 60 | {
 61 |     $this->factory = $factory;
 62 | 
 63 |     return $this;
 64 | }
 65 | ```
 66 | 
 67 | After the factory is injected, we can use it in our FormType specification for
 68 | defining the `empty_data` value and the `data_class`.
 69 | 
 70 | ``` php
 71 | /**
 72 |  * Default form options
 73 |  *
 74 |  * @param OptionsResolverInterface $resolver
 75 |  *
 76 |  * @return array With the options
 77 |  */
 78 | public function setDefaultOptions(OptionsResolverInterface $resolver)
 79 | {
 80 |     $resolver->setDefaults([
 81 |         'empty_data' => function () {
 82 |             $this
 83 |                 ->factory
 84 |                 ->create();
 85 |         },
 86 |         'data_class' => $this
 87 |             ->factory
 88 |             ->getEntityNamespace(),
 89 |     ]);
 90 | }
 91 | ```
 92 | 
 93 | In order to make things easier, there is a Trait in the package `elcodi/core`, 
 94 | designed as a Factory container. To use it, just add it in your class, like any
 95 | other trait, and you will be able to use the `$this->factory` in your class.
 96 | 
 97 | ``` php
 98 | use Elcodi\Component\Core\Factory\Traits\FactoryTrait;
 99 | 
100 | /**
101 |  * Class BannerType
102 |  */
103 | class BannerType extends AbstractType
104 | {
105 |     use FactoryTrait;
106 |     
107 |     /**
108 |      * Default form options
109 |      *
110 |      * @param OptionsResolverInterface $resolver
111 |      *
112 |      * @return array With the options
113 |      */
114 |     public function setDefaultOptions(OptionsResolverInterface $resolver)
115 |     {
116 |         $resolver->setDefaults([
117 |             'empty_data' => function () {
118 |                 $this
119 |                     ->factory
120 |                     ->create();
121 |             },
122 |             'data_class' => $this
123 |                 ->factory
124 |                 ->getEntityNamespace(),
125 |         ]);
126 |     }
127 | }
128 | ```
129 | 
130 | ### Using namespaces
131 | 
132 | If your FormType has any kind of relation with another entity, you will need to
133 | define this relation using a namespace. In order to comply again with the
134 | flexibility, we need to inject all namespaces using the entity manager 
135 | parameter.
136 | 
137 | These namespaces in Elcodi must be injected through the class constructor.
138 | 
139 | ``` php
140 | /**
141 |  * Class BannerType
142 |  */
143 | class BannerType extends AbstractType
144 | {
145 |     use FactoryTrait;
146 | 
147 |     /**
148 |      * @var string
149 |      *
150 |      * Image namespace
151 |      */
152 |     protected $imageNamespace;
153 | 
154 |     /**
155 |      * Construct
156 |      *
157 |      * @param string $imageNamespace Image namespace
158 |      */
159 |     public function __construct($imageNamespace)
160 |     {
161 |         $this->imageNamespace = $imageNamespace;
162 |     }
163 | 
164 |     /**
165 |      * buildForm function
166 |      *
167 |      * @param FormBuilderInterface $builder the formBuilder
168 |      * @param array                $options the options for this form
169 |      */
170 |     public function buildForm(FormBuilderInterface $builder, array $options)
171 |     {
172 |         $builder
173 |             ->add('image', 'entity', [
174 |                 'class'    => $this->imageNamespace,
175 |                 'required' => false,
176 |                 'label'    => 'image',
177 |                 'multiple' => false,
178 |             ]);
179 |     }
180 | }
181 | ```
182 |     
183 | ### FormType as a service
184 | 
185 | We are using dependencies in our FormTypes, so remember that we need to define 
186 | our classes as services.
187 | 
188 | ``` yaml
189 | services:
190 | 
191 |     #
192 |     # Form Types
193 |     #
194 |     elcodi.admin.banner.form_type.banner:
195 |         class: Elcodi\Admin\BannerBundle\Form\Type\BannerType
196 |         arguments:
197 |             - %elcodi.entity.image.class%
198 |         calls:
199 |             - [setFactory, [@elcodi.factory.banner]]
200 |         tags:
201 |             - { name: form.type, alias: elcodi_admin_banner_form_type_banner }
202 | ```
203 | 
204 | The alias of the FormType must be the same as the value returned by the method
205 | `getName()` of the class
206 | 
207 | ``` php
208 | /**
209 |  * Return unique name for this form
210 |  *
211 |  * @return string
212 |  */
213 | public function getName()
214 | {
215 |     return 'elcodi_admin_banner_form_type_banner';
216 | }
217 | ```
218 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/implementation/implement-a-repository.md:
--------------------------------------------------------------------------------
 1 | # How to Implement a Repository
 2 | 
 3 | Creating a repository in Elcodi is easy. Elcodi type repositories are used in the same
 4 | way Symfony uses its repository classes.
 5 | 
 6 | ## Scenario
 7 | 
 8 | We have created a new entity properly, and we are happy about that. We have a 
 9 | new service that must create a specific search against this new entity, and we
10 | need some nice class to place this logic
11 | 
12 | What people need to create complicated search queries, they are used to placing
13 | all this logic inside their services using the repository. Great, this can be a
14 | good decision if you're not planning to test your application. If you want, then
15 | you should use your repositories as are meant to be used: one repository per 
16 | entity with all specific query logic.
17 | 
18 | ## Solution
19 | 
20 | Each entity has its own Repository. You will find all entities related 
21 | repositories inside the Components, hosted in `Repository/` folders.
22 | 
23 | All of them are mostly empty, because they extend `AbstractRepository` and, thereby
24 | default, have a set of accessible public methods. However some of them have custom
25 | methods in order to build specific and complex queries.
26 | 
27 | ## Related Links
28 | 
29 | * [Symfony docs - Custom repository classes]http://symfony.com/doc/current/book/doctrine.html#custom-repository-classes)


--------------------------------------------------------------------------------
/manuscript/cookbook/implementation/implement-an-entity.md:
--------------------------------------------------------------------------------
  1 | # How to Implement an Entity
  2 | 
  3 | In Elcodi we use an extremely thin model. It means that our entities are just
  4 | parameters, getters and setters.
  5 | 
  6 | ## Scenario
  7 | 
  8 | Our website must start managing warehouses. We must be able to create new
  9 | warehouses, edit them and deleting them, as well as create new associations 
 10 | between warehouses and locations, in order to locate them.
 11 | 
 12 | Our model needs to change, so our application should be enough robust to be 
 13 | changed without many pain.
 14 | 
 15 | ## Solution
 16 | 
 17 | In order to change our model, we need to create a new entity following the 
 18 | standards of Elcodi.
 19 | 
 20 | Creating an entity is as easy as defining what an actor should own (parameters),
 21 | forgetting about the behavior of this one. This logic will be placed then in the 
 22 | service layer.
 23 | 
 24 | Let's see a basic implementation of an entity.
 25 | 
 26 | ``` php
 27 | class Warehouse
 28 | {
 29 |     /**
 30 |      * @var name
 31 |      *
 32 |      * Product name
 33 |      */
 34 |     protected $name;
 35 |      
 36 |     /**
 37 |      * Get name
 38 |      *
 39 |      * @return string Product name
 40 |      */
 41 |     public function getName()
 42 |     {
 43 |         return $this->name;
 44 |     }
 45 |     
 46 |     /**
 47 |      * Set name
 48 |      *
 49 |      * @param string $name Product name
 50 |      *
 51 |      * @return $this Self object
 52 |      */
 53 |     public function setName($name)
 54 |     {
 55 |         $this->name = $name;
 56 |         
 57 |         return $this;
 58 |     }
 59 | }
 60 | ```
 61 | 
 62 | As you can see all properties are defined as protected. This is because Doctrine
 63 | will need to extend the class using [transparent Proxy Objects](http://doctrine-orm.readthedocs.org/en/latest/reference/advanced-configuration.html#proxy-objects)
 64 | to implement lazy-loading.
 65 | 
 66 | ### Using Interfaces
 67 | 
 68 | All Elcodi entities are an implementation of a [
 69 | Header Interface](http://martinfowler.com/bliki/HeaderInterface.html).
 70 | We use some 
 71 | [Role Interfaces](http://martinfowler.com/bliki/RoleInterface.html) in
 72 | our code, but we are more focused in the first one because is more 
 73 | understandable for everyone when overriding default implementations.
 74 | 
 75 | ``` php
 76 | use MyComponent\Warehouse\Entity\Interfaces\WarehouseInterface;
 77 | 
 78 | /**
 79 |  * Class Warehouse
 80 |  */
 81 | class Warehouse implements WarehouseInterface
 82 | {
 83 |     // ...
 84 | }
 85 | ```
 86 | 
 87 | ### Using SimpleDoctrineMapping
 88 | 
 89 | Usually, final projects need to implement more entities inside their projects.
 90 | Since now, this has been so easy but so magical, and once again, we really think
 91 | that this stuff should never be magic at all. Is your model, your business.
 92 | 
 93 | In our actual implementation, we are using an Open Source project called 
 94 | [SimpleDoctrineMapping](https://github.com/mmoreram/SimpleDoctrineMapping). 
 95 | You should read carefully the documentation, indeed we strongly recommend it.
 96 | 
 97 | Yes, we need to say that, we'll need to disable the `auto_mapping` configuration 
 98 | item inside DoctrineBundle. This flag allow this magic we really want to avoid.
 99 | 
100 | Instead of that, we will specifically define how our entities should be defined
101 | and treated inside our project.
102 | 
103 | ## Related links
104 | 
105 | * [SimpleDoctrineMapping Docs](https://github.com/mmoreram/SimpleDoctrineMapping)


--------------------------------------------------------------------------------
/manuscript/cookbook/implementation/implement-an-event-listener.md:
--------------------------------------------------------------------------------
  1 | # How to implement an Event Listener
  2 | 
  3 | One of the good reasons to work with Symfony is because has a great and big
  4 | extension point. Symfony uses it's own Event Dispatcher component.
  5 | 
  6 | # Scenario
  7 | 
  8 | Our project needs to grow with new features related to existing ones. Because of
  9 | Elcodi is always installed as a vendor, we should not be able to modify it at 
 10 | all. For example, each time an order is created, we should be able to send the
 11 | administrator of the website a new email.
 12 | 
 13 | We need to know how Event Listeners must be created in order to use them 
 14 | properly, using Elcodi best practices and naming conventions.
 15 | 
 16 | # Solution
 17 | 
 18 | When we talk about Event Listeners in Symfony, we should think about a service 
 19 | with an extra layer of configuration. For example, following the example exposed
 20 | above, let's create a new service that sends that email we need.
 21 | 
 22 | Of course, this is not only a service but an EventListener, so the chosen method
 23 | must accept only one parameter. Depending of the event you want to hook your 
 24 | method, you will receive one Event type or other.
 25 | 
 26 | > You should know something about the Event Dispatcher from Symfony. We strongly
 27 | > recommend you to read something about it before continue reading this 
 28 | > documentation.
 29 | 
 30 | Each type of event is associated with a different type of event instance, so you
 31 | should 
 32 | 
 33 | ``` php
 34 | use Elcodi\Component\Cart\Entity\Interfaces\OrderInterface;
 35 | use Elcodi\Component\Cart\Event\OrderOnCreatedEvent;
 36 | 
 37 | /**
 38 |  * This class is intended to send an Email when any order is created
 39 |  */
 40 | class OrderEmailSenderEventListener
 41 | {
 42 |     /**
 43 |      * @var string
 44 |      *
 45 |      * Address where the email has to be sent
 46 |      */
 47 |     private $email;
 48 | 
 49 |     /**
 50 |      * Send an email to the administrator of the website, once an Order has been
 51 |      * successfully created.
 52 |      *
 53 |      * @param OrderOnCreatedEvent $event Order on Created event
 54 |      *
 55 |      * @return $this Self object
 56 |      */
 57 |     public function sendEmail(OrderOnCreatedEvent $event)
 58 |     {
 59 |         $order = $event->getOrder();
 60 |         // Send that email using $this->email!
 61 |      
 62 |         return $this;
 63 |     }
 64 | }
 65 | ```
 66 | 
 67 | ### Isolating your business logic
 68 | 
 69 | Our last implementation has one issue if you consider important your business
 70 | logic.
 71 | 
 72 | Imagine that you need to send this email from another service. Of course, this
 73 | service should know nothing about any kind of event, so, using last 
 74 | implementation, something is clearly wrong.
 75 | 
 76 | Let's see how we can fix improve this by doing just some small changes!
 77 | 
 78 | ``` php
 79 | use Elcodi\Component\Cart\Entity\Interfaces\OrderInterface;
 80 | use Elcodi\Component\Cart\Event\OrderOnCreatedEvent;
 81 | 
 82 | /**
 83 |  * This class is intended to send an Email when any order is created
 84 |  */
 85 | class OrderEmailSenderEventListener
 86 | {
 87 |     /**
 88 |      * @var string
 89 |      *
 90 |      * Address where the email has to be sent
 91 |      */
 92 |     private $email;
 93 | 
 94 |     /**
 95 |      * Send an email to the administrator of the website, once an Order has been
 96 |      * successfully created.
 97 |      *
 98 |      * @param OrderOnCreatedEvent $event Order on Created event
 99 |      *
100 |      * @return $this Self object
101 |      */
102 |     public function sendEmail(OrderOnCreatedEvent $event)
103 |     {
104 |         $order = $event->getOrder();
105 |         $this->sendEmailByOrderAndEmail(
106 |             $order,
107 |             $this->email
108 |         );
109 |      
110 |         return $this;
111 |     }
112 |      
113 |      /**
114 |       * Send an specific email given an order instance and the address where the
115 |       * email must be sent
116 |       *
117 |       * @param OrderInterface $order Order
118 |       * @param string         $email Email
119 |       *
120 |       * @return $this Self object
121 |       */
122 |     public function sendEmailByOrderAndEmail(OrderInterface $order, $email)
123 |     {
124 |         // Send that email using $this->email!
125 |       
126 |         return $this;
127 |     }
128 | }
129 | ```
130 | 
131 | With this implementation you can still be listening to the `order.oncreated`
132 | event, and your business logic can be accessed from any point of entry.
133 | 
134 | ### Using Dependency Injection Tags
135 | 
136 | Once the class is created and tested, we should add this extra configuration
137 | layer in our Dependency Injection definition. And we will do such thing by using
138 | tags.
139 | 
140 | > Once again, this is not Elcodi related, but Symfony. You can check a little 
141 | > bit more information by checking the Symfony Docs
142 | 
143 | Let's see an example of how this configuration could be.
144 | 
145 | ``` yaml
146 | services:
147 |     
148 |     elcodi.event_listener.order_email_sender:
149 |         class: My\Bundle\EventListener\OrderEmailSenderEventListener
150 |         arguments:
151 |             - %administrator_email%
152 |         tags:
153 |             - { name: kernel.event_listener, event: order.oncreated, method: sendEmail }
154 | ```
155 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/index.md:
--------------------------------------------------------------------------------
 1 | Cookbook
 2 | ========
 3 | 
 4 | The Elcodi Cookbook is a set of recipes related to Elcodi development flow and
 5 | the Bamboo implementation. Each one solves a specific problem or a specific
 6 | scenario and follows this format.
 7 | 
 8 | Scenario - Scenario where this cookbook has sense
 9 | Problem - What we need to do?
10 | Solution - Solve it that way!
11 | Related links - Set of internal and external related links
12 | 
13 | ### Implementation
14 | 
15 | * [How to Implement an Entity](http://elcodi.io/docs/cookbook/implementation/implement-an-entity/)
16 | * [How to Implement a Factory](http://elcodi.io/docs/cookbook/implementation/implement-a-factory/)
17 | * [How to Implement a Repository](http://elcodi.io/docs/cookbook/implementation/implement-a-repository/)
18 | * [How to Implement a Form Type](http://elcodi.io/docs/cookbook/implementation/implement-a-form-type/)
19 | * [How to Implement a Controller or a Command](http://elcodi.io/docs/cookbook/implementation/implement-a-controller-and-a-command/)
20 | * [How to Implement a Collector](http://elcodi.io/docs/cookbook/implementation/implement-a-collector/)
21 | 
22 | ### Installation
23 | 
24 | * [How to Install Dependent Bundles](http://elcodi.io/docs/cookbook/installation/install-dependent-bundles/)
25 | * [How to Install a Plugin](http://elcodi.io/docs/cookbook/installation/install-a-plugin/)
26 | 
27 | ### Usage
28 | 
29 | * [How to Use Referrer Domain](http://elcodi.io/docs/cookbook/usage/referrer-domain/)
30 | * [How to Use Elcodi Watermark](http://elcodi.io/docs/cookbook/usage/elcodi-watermark/)
31 | 
32 | ### Overwrite Elcodi & Bamboo
33 | 
34 | * [How to Overwrite a Parameter](http://elcodi.io/docs/cookbook/overwrite/overwrite-a-parameter/)
35 | * [How to Overwrite an Entity](http://elcodi.io/docs/cookbook/overwrite/overwrite-an-entity/)
36 | * [How to Overwrite a Service](http://elcodi.io/docs/cookbook/overwrite/overwrite-a-service/)
37 | 
38 | ### Adapters
39 | 
40 | * [How to add a new Currency Rates Populator adapter](http://elcodi.io/docs/cookbook/adapters/currency-rates-populator/)
41 | * [How to add a new Image Resize adapter](http://elcodi.io/docs/cookbook/adapters/image-resize/)
42 | * [How to add a new Metric Bucket adapter](http://elcodi.io/docs/cookbook/adapters/metric-bucket/)
43 | * [How to add a new Location Provider adapter](http://elcodi.io/docs/cookbook/adapters/location-provider/)
44 | * [How to add a new Location Populator adapter](http://elcodi.io/docs/cookbook/adapters/location-populator/)
45 | * [How to add a new Location Loader adapter](http://elcodi.io/docs/cookbook/adapters/location-loader/)
46 | * [How to add a new Related Purchasables Provider adapter](http://elcodi.io/docs/cookbook/adapters/related-purchasables-provider/)
47 | 
48 | ## Ask your cookbook
49 | 
50 | Of course, we cannot think about all problems a project can produce. And this is
51 | because there are a lot of possible scenarios you fill find yourself lost and
52 | with some helping needs.
53 | 
54 | Don't worry. Do you need how to do something that is not documented yet? Ask us
55 | and we will take care of all these things:
56 | 
57 | * Helping you with that problem on Gitter. Please, join us at
58 | [elcodi/elcodi room](http://gitter.im/elcodi/elcodi) and ask us whatever you
59 | need.
60 | * Adding the cookbook entry with the "How to..." text
61 | * If the problem is common, we will create a new blog post explaining the
62 | solution
63 | 
64 | ## Add your cookbook entry
65 | 
66 | Have you solved something interesting? Then, we are interested in knowing what
67 | did you solve and how did you do that.
68 | 
69 | You can propose your new material by following the
70 | [Pull Request Book chapter](http://elcodi.io/docs/book/pull-requests/). If you need some help
71 | about how to do that, we can improve as well this chapter in order to make it
72 | more clear and easy.
73 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/installation/install-a-plugin.md:
--------------------------------------------------------------------------------
 1 | How to Install a plugin
 2 | =======================
 3 | 
 4 | To read about plugins, please read all the 
 5 | [Plugins Chapter](http://elcodi.io/docs/book/plugins/) of our book.
 6 | 
 7 | To install a plugin, you must treat it as a simple third party bundle.
 8 | 
 9 | * Add the plugin (bundle) in your composer dependencies
10 | * Update your dependencies by using *composer update*
11 | * Add the bundle in your kernel
12 | 
13 | But because a Plugin is not only a Bundle, this is not enough. Bamboo offers you
14 | a very easy way of updating the information of your plugins by using a command.
15 | It only takes 2 seconds!
16 | 
17 | ``` bash
18 | php app/console elcodi:plugins:load
19 | ```
20 | 
21 | Your already loaded plugin data will not be updated unless some plugin has 
22 | changed its configuration structure. Please pay attention to your dependencies
23 | versions.
24 | 
25 | After this command, your will be able to manage your plugins through your admin
26 | panel.


--------------------------------------------------------------------------------
/manuscript/cookbook/installation/install-dependent-bundles.md:
--------------------------------------------------------------------------------
  1 | # How to Install dependent Bundles
  2 | 
  3 | This chapter is not only to show how to install a Dependent Bundle in Elcodi 
  4 | environment, but to show how to do it properly.
  5 | 
  6 | ### Package dependencies
  7 | 
  8 | All Bundles in Elcodi follow the same installation strategy than Symfony 
  9 | standard packages. Elcodi uses composer for package dependencies, so each
 10 | standalone Elcodi repository comes with a properly configured `composer.json` 
 11 | file.
 12 | 
 13 | But when we talk about Bundles in Symfony, defining the dependencies in the
 14 | composer file is not enough. The Kernel will instance only the Bundles you
 15 | define in `AppKernel.php` file, ignoring the real dependencies this Bundle has.
 16 | 
 17 | So, regarding this real problem, Elcodi has developed some business logic in
 18 | order to solve this problem.
 19 | 
 20 | First of all, let's take a look at a simple Symfony Bundle class.
 21 | 
 22 | ``` php
 23 | /**
 24 |  * ElcodiCartBundle Bundle
 25 |  */
 26 | class ElcodiCartBundle extends Bundle
 27 | {
 28 | }
 29 | ```
 30 | 
 31 | Maybe this Bundle needs the instantiation of another bundle (previously added in
 32 | the composer definition), but is not defined anywhere. So... let's do that.
 33 | 
 34 | The first step is to define a set of Bundle namespaces that must be instanced
 35 | before this Bundle.
 36 | 
 37 | All dependent Bundles will be instanced before this Bundle. This is because a
 38 | Bundle should be able to override another Bundle definition, and Symfony has in
 39 | most cases a **Last defined wins** strategy.
 40 | 
 41 | ``` php
 42 | use Symfony\Component\HttpKernel\Bundle\Bundle;
 43 | use Elcodi\Bundle\CoreBundle\Interfaces\DependentBundleInterface;
 44 | 
 45 | /**
 46 |  * ElcodiCartBundle Bundle
 47 |  */
 48 | class ElcodiCartBundle extends Bundle implements DependentBundleInterface
 49 | {
 50 |     /**
 51 |      * Create instance of current bundle, and return dependent bundle namespaces
 52 |      *
 53 |      * @return array Bundle instances
 54 |      */
 55 |     public static function getBundleDependencies()
 56 |     {
 57 |         return [
 58 |             'Elcodi\Bundle\UserBundle\ElcodiUserBundle',
 59 |             'Elcodi\Bundle\ProductBundle\ElcodiProductBundle',
 60 |             'Elcodi\Bundle\CurrencyBundle\ElcodiCurrencyBundle',
 61 |             'Elcodi\Bundle\StateTransitionMachineBundle\ElcodiStateTransitionMachineBundle',
 62 |             'Elcodi\Bundle\ShippingBundle\ElcodiShippingBundle',
 63 |             'Elcodi\Bundle\ConfigurationBundle\ElcodiConfigurationBundle',
 64 |             'Elcodi\Bundle\CoreBundle\ElcodiCoreBundle',
 65 |         ];
 66 |     }
 67 | }
 68 | ```
 69 | 
 70 | So, what else? Is that enough?
 71 | 
 72 | Then, in order to make it happen, we must use a specific method in our 
 73 | `AppKernel` class, using a Trait provided by `ElcodiCoreBundle`.
 74 | 
 75 | ``` php
 76 | use Elcodi\Bundle\CoreBundle\Traits\BundleDependenciesResolver;
 77 | use Elcodi\Bundle\TestCommonBundle\Functional\Abstracts\AbstractElcodiKernel;
 78 | 
 79 | /**
 80 |  * Class AppKernel
 81 |  */
 82 | class AppKernel extends AbstractElcodiKernel
 83 | {
 84 |     use BundleDependenciesResolver;
 85 |     
 86 |     /**
 87 |      * Register application bundles
 88 |      *
 89 |      * @return array Array of bundles instances
 90 |      */
 91 |     public function registerBundles()
 92 |     {
 93 |         return $this->getBundleInstances([
 94 |             '\Elcodi\Bundle\CartBundle\ElcodiCartBundle',
 95 |         ]);
 96 |     }
 97 | }
 98 | ```
 99 | 
100 | And that's it. Your kernel will instance your `ElcodiCartBundle` bundle and all
101 | its dependencies.
102 | 
103 | > This method will work as well, even if the Bundle has no dependencies or is
104 | > not extending DependentBundleInterface.
105 | 
106 | ### Using dependencies in your project
107 | 
108 | If you want to use this classes and methods in your Symfony project, you don't 
109 | really need to instance `ElcodiCoreBundle` because you will not need any kind
110 | of Dependency Injection definition.
111 | 
112 | You only need to add `elcodi/core-bundle` in your package requirements and then
113 | use the Interface and the Trait as is shown in this CookBook entry.


--------------------------------------------------------------------------------
/manuscript/cookbook/overwrite/overwrite-a-parameter.md:
--------------------------------------------------------------------------------
 1 | How to Overwrite a Parameter
 2 | ============================
 3 | 
 4 | You can overwrite Elcodi by using the file `app/config/config_local.yml`. This
 5 | file is loaded at the end of the `app/config/config.yml` file, allowing final 
 6 | users to add custom elements, overriding all project definitions.
 7 | 
 8 | Why you should use `config_local.yml` file?
 9 | 
10 | Well, this file will never be improved nor evolved, so even if you pull into 
11 | your project last Elcodi versions, you will never have conflicts in that file.
12 | 
13 | Let's see an example
14 | 
15 | ``` yaml
16 | # app/config/config_local.yml
17 | parameters:
18 |     database_host: 10.0.0.1
19 | 
20 | elcodi_currency:
21 |     currency:
22 |         default_currency: EUR
23 |         session_field_name: currency_id
24 | ```
25 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/overwrite/overwrite-a-service.md:
--------------------------------------------------------------------------------
 1 | # How to overwrite a service
 2 | 
 3 | The Elcodi's default service layer is kindly proposed by the project in order to
 4 | provide you a simple business logic, documented, and with all capabilities to be
 5 | modified, overwritten and changed as much as needed.
 6 | 
 7 | ## Scenario
 8 | 
 9 | Imagine your E-commerce needs have evolved a lot, and your business needs grow
10 | day by day. Your Cart is not Elcodi's cart anymore and you need to change a 
11 | little bit
12 | 
13 | Your Product needs an extra flag called `promoted`, in order to assign an extra
14 | promotional value from 0 to 1, and used when products are required for 
15 | pagination. Your Product, based on Elcodi's one, should have this new field.
16 | 
17 | ## Solution
18 | 
19 | To overwrite a service you must create a new class in your project, extend the 
20 | main service and overwrite the methods you need to overwrite.
21 | 
22 | ``` php
23 | use Elcodi\Component\Cart\Services\CartManager;
24 | 
25 | /**
26 |  * New cart manager
27 |  */
28 | class NewCartManager extends CartManager
29 | {
30 |     /**
31 |      * Adds cartLine to Cart
32 |      *
33 |      * This method dispatches all Cart Check and Load events
34 |      * It should NOT be used to add a Purchasable to a Cart,
35 |      * by manually passing a newly crafted CartLine, since
36 |      * no product duplication check is performed: in that
37 |      * case CartManager::addProduct should be used
38 |      *
39 |      * @param CartInterface     $cart     Cart
40 |      * @param CartLineInterface $cartLine Cart line
41 |      *
42 |      * @return $this Self object
43 |      */
44 |     protected function addLine(
45 |         CartInterface $cart,
46 |         CartLineInterface $cartLine
47 |     ) {
48 |     
49 |         // My own addLine implementation
50 |     }
51 | }
52 | ```
53 | 
54 | Finally we need to let the project know that this new implementation is the one
55 | we really want to use in our project. For this reason, we should redefine this
56 | service in our `config.yml` file, and overwrite the main service implementation.
57 | 
58 | ``` yaml
59 | services:
60 | 
61 |     elcodi.manager.cart:
62 |         cart: My\New\Bundle\Services\NewCartManager
63 |         arguments:
64 |             ...
65 | ```
66 | 
67 | Having done that, all the project will use your `elcodi.manager.cart` 
68 | implementation instead of the default one.
69 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/overwrite/overwrite-an-entity.md:
--------------------------------------------------------------------------------
  1 | # How to Overwrite an Entity
  2 | 
  3 | Each project is completely different, right? Elcodi is just one approach to an
  4 | specific e-commerce problem, but one of our goals is to provide a way for
  5 | overwriting absolutely everything.
  6 | 
  7 | ## Scenario
  8 | 
  9 | Your E-commerce installation is great, but the Product implementation that 
 10 | Elcodi proposes to you as a base is not enough for your model requirements.
 11 | 
 12 | Your Product needs an extra flag called `promoted`, in order to assign an extra
 13 | promotional value from 0 to 1, and used when products are required for 
 14 | pagination. Your Product, based on Elcodi's one, should have this new field.
 15 | 
 16 | ## Solution
 17 | 
 18 | The solution is very easy. From this moment your Product implementation will be 
 19 | the one used in your project, instead of the old one. This means that you will
 20 | be able to extend it as much as you want without modifying the old one, just
 21 | extending or re-implementing it.
 22 | 
 23 | ### Extending or Implementing
 24 | 
 25 | Each entity has its own interface. It means that if you want to build your own
 26 | `Product`, for example, your new implementation will need to implement the 
 27 | existing ProductInterface, in that case, 
 28 | `Elcodi\Component\Product\Entity\Interfaces\ProductInterface`.
 29 | 
 30 | ``` php
 31 | use Elcodi\Component\Product\Entity\Interfaces\ProductInterface;
 32 | 
 33 | /**
 34 |  * New Product implementation
 35 |  */
 36 | class NewProduct implements ProductInterface
 37 | {
 38 |     ...
 39 | }    
 40 | ```
 41 | 
 42 | This is useful when you really want to implement another Product completely 
 43 | different than the old one, but with same specification.
 44 | 
 45 | You can also create a new entity extending the default Product implementation (at 
 46 | this point your new entity will be implementing this interface by default). The 
 47 | advantage is that you don't need to implement all the methods of the interface, 
 48 | but just overwrite those that you want to change.
 49 | 
 50 | Perfect if you only need to extend it.
 51 | 
 52 | ``` php
 53 | use Elcodi\Component\Product\Entity\Product;
 54 | 
 55 | /**
 56 |  * New Product implementation
 57 |  */
 58 | class NewProduct extends Product
 59 | {
 60 |     /**
 61 |      * @var boolean
 62 |      *
 63 |      * Promoted value
 64 |      */
 65 |     protected $promoted;
 66 |      
 67 |      /**
 68 |       * Get promoted value
 69 |       *
 70 |       * @return float Promoted value
 71 |       */
 72 |      public function getPromoted()
 73 |      {
 74 |         return $this->promoted;
 75 |      }
 76 |      
 77 |      /**
 78 |       * Set promoted value
 79 |       *
 80 |       * @param float $promoted Promoted value
 81 |       *
 82 |       * @return $this Self object
 83 |       */
 84 |      public function setPromoted($promoted)
 85 |      {
 86 |         $this->promoted = $promoted;
 87 |      
 88 |         return $this;
 89 |      }
 90 | }    
 91 | ```
 92 | 
 93 | Both ways are valid depending on your implementation needs, but given our needs,
 94 | we will use this one.
 95 | 
 96 | ### Using this new implementation
 97 | 
 98 | Once your new entity is implemented, you need to tell your application
 99 | about your new implementation.
100 | 
101 | Elcodi works with a project called 
102 | [SimpleDoctrineMapping](https://github.com/mmoreram/SimpleDoctrineMapping). This
103 | library enables each bundle to specify how its entities must be treated inside
104 | the Symfony installation, instead of letting Doctrine decide this stuff using 
105 | `auto_mapping=true`.
106 | 
107 | Each Elcodi Bundle uses this library, so you can overwrite this information 
108 | through each Bundle configuration. Let's see how ProductBundle allows the user to
109 | define this information by exposing its configuration.
110 | 
111 | ``` yaml
112 | elcodi_product:
113 |     
114 |     mapping:
115 |         product:
116 |             # Product entity implementing ProductInterface
117 |             class: Elcodi\Component\Product\Entity\Product
118 |             # Doctrine mapping file for this entity
119 |             mapping_file: '@ElcodiProductBundle/Resources/config/doctrine/Product.orm.yml'
120 |             # Doctrine manager name
121 |             manager: default
122 |             # Is this entity enabled?
123 |             enabled: true
124 | ```
125 | 
126 | If you don't define anything, then these values are injected as default 
127 | configuration values in ProductBundle, so this is the way of overwriting the 
128 | definition to start using our new Product implementation.
129 | 
130 | ``` yaml
131 | elcodi_product:
132 |     
133 |     mapping:
134 |         product:
135 |             # Product entity implementing ProductInterface
136 |             class: My\New\Bundle\Entity\NewProduct
137 | ```
138 | 
139 | And that's enough.
140 | 
141 | ### Changing the mapping file
142 | 
143 | Once you have changed your entity, or just using the default entity 
144 | implementation, maybe you want to change the way the entity is mapped in your
145 | database.
146 | 
147 | ``` yaml
148 | elcodi_product:
149 |     
150 |     mapping:
151 |         product:
152 |             # Product entity implementing ProductInterface
153 |             class: My\New\Bundle\Entity\NewProduct
154 |             # Doctrine mapping file for this entity
155 |             mapping_file: '@MyNewBundle/Resources/config/doctrine/Product.orm.yml'
156 | ```
157 | 
158 | In Elcodi we are actually using `yml` files for such definition, but you can use
159 | both `yml` and `xml` files.
160 | 
161 | ``` yaml
162 | elcodi_product:
163 |     
164 |     mapping:
165 |         product:
166 |             # Product entity implementing ProductInterface
167 |             class: My\New\Bundle\Entity\NewProduct
168 |             # Doctrine mapping file for this entity
169 |             mapping_file: '@MyNewBundle/Resources/config/doctrine/Product.orm.xml'
170 | ```
171 | 
172 | The result will be the same, and the system will detect the file extension.
173 | 
174 | ### Overwriting the mapping file
175 | 
176 | Once you need to overwrite the mapping file, you need to do it completely. 
177 | Doctrine implementation does not allow overwriting a mapping file, so you need
178 | to copy/paste the old one and modify as you wish.
179 | 
180 | In fact, this is the best option. As long as you don't use anymore the mapping 
181 | file proposed by Elcodi, then you should take the control of all the mapping 
182 | file.
183 | 
184 | ### Using another Entity Manager
185 | 
186 | By default, all entities are managed by the default entity manager. You can 
187 | change this behavior just overwriting this configuration value. The selected 
188 | entity manager must exist in your Doctrine ORM definition.
189 | 
190 | ``` yaml
191 | elcodi_product:
192 |     
193 |     mapping:
194 |         product:
195 |             # Product entity implementing ProductInterface
196 |             class: My\New\Bundle\Entity\NewProduct
197 |             # Doctrine mapping file for this entity
198 |             mapping_file: '@MyNewBundle/Resources/config/doctrine/Product.orm.yml'
199 |             # Doctrine manager name
200 |             manager: another_entity_manager
201 | ```
202 | 
203 | Take into account that related entities should share the same entity manager. 
204 | For example, in this example, because `Product` is related to `Category`, it 
205 | would be not possible to have both tables managed separately by two different 
206 | managers.
207 | 
208 | ### Disabling an Entity
209 | 
210 | Maybe you want to disable a specific entity. The most used strategy would be not
211 | to use this entity, even if the table is created, but we strongly think that 
212 | your model must be considered an essential part of your implementation, so you 
213 | can disable an entity with a single line.
214 | 
215 | ``` yaml
216 | elcodi_product:
217 |     
218 |     mapping:
219 |         product:
220 |             enabled: false
221 | ```
222 | 


--------------------------------------------------------------------------------
/manuscript/cookbook/usage/elcodi-watermark.md:
--------------------------------------------------------------------------------
 1 | # Elcodi Watermark
 2 | 
 3 | We need a small watermark for all Elcodi E-commerce implementation. This
 4 | watermark should be very soft, small and imperceptible by the human eye, only
 5 | accessible by developers and robots.
 6 | 
 7 | We want to introduce you a Symfony Bundle called
 8 | [HTTPHeadersBundle](https://github.com/mmoreram/HTTPHeadersBundle). This bundle
 9 | is very basic, only 2 PHP classes indeed. You can read there the documentation,
10 | and we will explain how we are using this project.
11 | 
12 | ## X-Elcodi
13 | 
14 | This is the Response HTTP Header for Elcodi. As you can see in the `config.yml`
15 | file in Bamboo, the HTTPHeadersBundle configuration sets this header for all
16 | site pages
17 | 
18 | ``` yaml
19 | #
20 | # HTTP Headers
21 | # Fill this data to ensure your ecommerce is unique and belongs to developers
22 | # Checkout the configuration in https://github.com/mmoreram/HTTPHeadersBundle
23 | #
24 | http_headers:
25 |     response:
26 |         x_elcodi:
27 |             name: X-Elcodi
28 |             values:
29 |                 - This E-commerce is built using Elcodi and Symfony
30 | ```
31 | 
32 | Please, this header will allow some engines to detect your website as an
33 | implementation of Elcodi. This means more installations, more development, and
34 | this always means more confidence for other people.


--------------------------------------------------------------------------------
/manuscript/cookbook/usage/referrer-domain.md:
--------------------------------------------------------------------------------
 1 | # Using referrer domain
 2 | 
 3 | You would possible know the referrer of your site views, right? Well, Bamboo
 4 | store provides you a couple of tools for this.
 5 | 
 6 | ## Referrer provider
 7 | 
 8 | in Elcodi Core component you will find the service with all business logic
 9 | related to this. A simple class that will allow you to know some information
10 | about your referrers.
11 | 
12 | ``` php
13 | namespace Elcodi\Component\Core\Services;
14 | 
15 | /**
16 |  * Class ReferrerProvider
17 |  */
18 | class ReferrerProvider
19 | {
20 |     /**
21 |      * Get referrer
22 |      *
23 |      * @return string Referrer
24 |      */
25 |     public function getReferrer();
26 |     
27 |     /**
28 |      * Get referrer
29 |      *
30 |      * @return string Referrer
31 |      */
32 |     public function getReferrerDomain();
33 |     
34 |     /**
35 |      * Referrer is search engine
36 |      *
37 |      * @return boolean Is search engine
38 |      */
39 |     public function referrerIsSearchEngine();
40 | }
41 | ```
42 | 
43 | You can inject this service by using the dependency injection service name.
44 | 
45 | ``` yml
46 | services:
47 |     my_service:
48 |         class: My\Service\Class;
49 |         arguments:
50 |             - @elcodi.provider.referrer
51 | ```
52 | 
53 | ## Referrer Twig extension
54 | 
55 | If you need to access to this information in the Twig layer, then there is an
56 | Extension for that.
57 | 
58 | ``` jinja
59 | {{ referrer() }}
60 | {{ referrer_domain() }}
61 | {{ referrer_is_search_engine() }}
62 | ```


--------------------------------------------------------------------------------
/manuscript/cookbook/workflow/create-automatic-coupon.md:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/cookbook/workflow/create-automatic-coupon.md


--------------------------------------------------------------------------------
/manuscript/images/category.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/category.png


--------------------------------------------------------------------------------
/manuscript/images/homepage.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/homepage.png


--------------------------------------------------------------------------------
/manuscript/images/login.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/login.png


--------------------------------------------------------------------------------
/manuscript/images/model-cart-cartline.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/model-cart-cartline.png


--------------------------------------------------------------------------------
/manuscript/images/model-cart-component.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/model-cart-component.png


--------------------------------------------------------------------------------
/manuscript/images/model-category.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/model-category.png


--------------------------------------------------------------------------------
/manuscript/images/model-order-orderline.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/model-order-orderline.png


--------------------------------------------------------------------------------
/manuscript/images/model-product-component.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/model-product-component.png


--------------------------------------------------------------------------------
/manuscript/images/product.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/product.png


--------------------------------------------------------------------------------
/manuscript/images/register.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/register.png


--------------------------------------------------------------------------------
/manuscript/images/title_page.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/title_page.png


--------------------------------------------------------------------------------
/manuscript/images/top-bar.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/top-bar.png


--------------------------------------------------------------------------------
/manuscript/images/variant.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elcodi/docs/d6dd4a66905fb60321149a0e2fda3067e72b1b36/manuscript/images/variant.png


--------------------------------------------------------------------------------
/manuscript/index.md:
--------------------------------------------------------------------------------
 1 | # Elcodi Documentation
 2 | 
 3 | This documentation is rendered online at 
 4 | [http://elcodi.io/docs](http://elcodi.io/docs)
 5 | 
 6 | * [Quick Start](http://elcodi.io/docs/quick-start/)
 7 | * [The Book](http://elcodi.io/docs/book/index.html)
 8 | * [The Components](http://elcodi.io/docs/component/index.html)
 9 | * [The Cookbook](http://elcodi.io/docs/cookbook/index.html)
10 | 
11 | 


--------------------------------------------------------------------------------
/manuscript/quick-start.md:
--------------------------------------------------------------------------------
  1 | Bamboo e-commerce
  2 | =================
  3 | 
  4 | Welcome to Bamboo e-commerce - a fully-functional e-commerce application built
  5 | using [Elcodi] components on top of the [Symfony] framework.
  6 | 
  7 | Yes, you got it right! Bamboo uses the Symfony framework but our components are
  8 | framework agnostic, that is, they only depend on the Symfony components as 
  9 | opposed to the whole framework or any of its distributions.
 10 | 
 11 | Why should I use Bamboo? That's simple, to sell your products. We provide you 
 12 | with an interface to sell your products and manage your store. You only have to 
 13 | focus on offering a good product, we take care of the rest.
 14 | 
 15 | ## Requirements
 16 | 
 17 | We're trying to build this project with a light default dependencies. These are
 18 | ours.
 19 | 
 20 | > The following dependencies are required for local installation, if you want we
 21 | > also provide a provisioning system to run bamboo on a virtual machine using 
 22 | > Vagrant. Read more about the
 23 | [Vagrant quickstart](http://elcodi.io/docs/book/vagrant-quick-start/).
 24 | 
 25 | ### PHP
 26 | 
 27 | To use Bamboo and Elcodi you need a PHP version not lower than **5.4**. For more 
 28 | info just visit their [installation page](http://php.net/manual/en/install.php)
 29 | 
 30 | ### PHP GD
 31 | 
 32 | > This PHP extension is used to being already installed when you add PHP in your
 33 | > distribution
 34 | 
 35 | Images are a really important part of an store. Bamboo uses PHP GD to
 36 | resize and optimize all product images. For more info just visit their
 37 | [installation page](http://php.net/manual/en/image.installation.php)
 38 | 
 39 | After that, you will be able to change the adapter and use other 
 40 | implementations.
 41 | 
 42 | ### MySQL
 43 | 
 44 | And, where do you save your data? By default we use MySQL, remember to install
 45 | it as well as its extension for PHP. For more info just visit their
 46 | [installation page](http://dev.mysql.com/doc/refman/5.1/en/installing.html)
 47 | 
 48 | ### Composer
 49 | 
 50 | [Composer] is required to manage dependencies.
 51 | 
 52 | if you have not yet installed Composer, download it following the instructions
 53 | on [http://getcomposer.org/](http://getcomposer.org/) or just run the following
 54 | command:
 55 | 
 56 | ``` bash
 57 | $ curl -s http://getcomposer.org/installer | php
 58 | ```
 59 | 
 60 | ## Installation
 61 | 
 62 | If you're used to working with LAMP environment, then you will have Bamboo 
 63 | running in your computer in less than 5 minutes.
 64 | 
 65 | ### 1. Install the project
 66 | 
 67 | After installing composer you can create your new Bamboo project.
 68 | 
 69 | ``` bash
 70 | $ php composer.phar create-project elcodi/bamboo bamboo -sdev
 71 | ```
 72 | 
 73 | > The installation process will ask you for some parameters like the database
 74 | > driver, username, password, database name, etc
 75 | 
 76 | Enter your directory to start the configuration step and use our magic command
 77 | to create a complete development environment. Just one single line to rule them
 78 | all
 79 | 
 80 | ``` bash
 81 | $ cd bamboo/
 82 | $ php app/console elcodi:install
 83 | ```
 84 | 
 85 | By default only Spain will be installed. We have focused this step to run as 
 86 | fast as possible, so then, you'll be able to install more countries. You can add
 87 | some countries in addition by using the `--country` command option.
 88 | 
 89 | ``` bash
 90 | $ php app/console elcodi:install --country=FR --country=IT
 91 | ```
 92 | 
 93 | ### 2. Run the server
 94 | 
 95 | Our store is ready to run. Use the built-in server to take a look at the 
 96 | project.
 97 | 
 98 | ``` bash
 99 | $ php app/console server:run
100 | ```
101 | 
102 | ### 3. Visit your store
103 | 
104 | You're done! Visit `http://localhost:8000` in your browser and take a look at
105 | what we have for you :) Use these Customer credentials in the store
106 | 
107 | ``` text
108 | Customer username: customer@customer.com
109 | Customer password: 1234
110 | ```
111 | 
112 | And for the admin panel, use this Admin credentials.
113 | 
114 | ``` text
115 | Admin username: admin@admin.com
116 | Admin password: 1234
117 | ```
118 | 
119 | Remember to remove these users properly as soon as you're in production.
120 | 
121 | 
122 | ## Metrics
123 | 
124 | Metrics are not enabled by default. If you want to enable them, then you need to
125 | install Redis. For more info just visit their
126 | [installation page](http://redis.io/topics/quickstart)
127 | 
128 | In order to use the last Redis features, like the `HyperLogLog` commands, be
129 | sure your Redis version is at least `v2.8.9`.
130 | 
131 | ## Cache
132 | 
133 | By default, Bamboo is installed without any doctrine cache. You can change this
134 | settings by changing the file `app/cache/config/common/cache.yml` and by
135 | changing the value `array` for another one.
136 | 
137 | You can check some documentation about different types of cache in the
138 | [Doctrine Cache Bundle](https://github.com/doctrine/DoctrineCacheBundle)
139 | repository page.
140 | 
141 | The most used cache type in Bamboo is `redis`. Make sure then that you have the
142 | php redis extension installed properly.
143 | 
144 | ## Tests
145 | 
146 | We are doing some tests, and this will be **in cresciendo**. You can ensure
147 | yourself that all the cases we've been working on are actually green. We are
148 | using Behat and PHPUnit, so you only need to execute all suites by using this
149 | piece of code.
150 | 
151 | ``` bash
152 | $ php bin/behat
153 | $ php bin/phpunit -c app
154 | $ php app/console visithor:go --format=pretty --env=test
155 | ```
156 | 
157 | ## Issues
158 | 
159 | You can report any issue on [github.com/elcodi/bamboo/issues](https://github.com/elcodi/bamboo/issues) or
160 | [github.com/elcodi/elcodi/issues](https://github.com/elcodi/elcodi/issues)
161 | 
162 | ## Need help
163 | 
164 | If you need any help with the installation or understanding elcodi or bamboo you
165 | can contact us on [gitter.im/elcodi/elcodi](https://gitter.im/elcodi/elcodi).
166 | We will be glad to help you, just ask for help.
167 | 
168 | [Composer]: http://getcomposer.org/
169 | [Symfony]: http://symfony.com
170 | [Elcodi]: https://github.com/elcodi/elcodi
171 | [configure a Web server]: http://symfony.com/doc/current/cookbook/configuration/web_server_configuration.html
172 | 


--------------------------------------------------------------------------------
/mkdocs.yml:
--------------------------------------------------------------------------------
 1 | site_name: Elcodi Documentation
 2 | site_url: http://www.elcodi.io/
 3 | site_description: Elcodi documentation website
 4 | 
 5 | repo_url: https://github.com/elcodi/docs
 6 | 
 7 | docs_dir: manuscript
 8 | theme_dir: elcodi
 9 | 
10 | markdown_extensions:
11 |     - toc:
12 |         permalink: " #"
13 | 
14 | copyright: Copyright © 2014/2015 <a href="http://www.elcodi.io">Elcodi</a>. All rights reserved.
15 | 


--------------------------------------------------------------------------------
/yuml.md:
--------------------------------------------------------------------------------
 1 | # Yuml graph definition
 2 | 
 3 | This page contains all this documentation uml definitions. Each one has the name
 4 | of the image stored locally and the definition for the website
 5 | [Yuml.me](http://yuml.me).
 6 | 
 7 | To build each image, append the value of the definition after
 8 | `http://yuml.me/diagram/scruffy/class/edit/`.
 9 | 
10 | ### manuscript/images/model/cart-component.png
11 | 
12 | [CartLine|cart;orderLine;purchasable]-1>[note: Purchasable Model{bg:cornsilk],  
13 | [OrderLine|order;cartLine;purchasable]-1>[note: Purchasable Model{bg:cornsilk],  
14 | [Cart|order;cartLines]1++-0..*>[CartLine],  
15 | [Order|cart;orderLines]<1-0..*>[OrderLine],  
16 | [Cart]<1-0..1>[Order],  
17 | [CartLine]<1-0..1>[OrderLine]
18 | 
19 | ![Cart component model](manuscript/images/model/cart-component.png)
20 | 
21 | ### manuscript/images/model/cart-cartline.png
22 | 
23 | [CartLine|cart;orderLine;purchasable]-1>[note: Purchasable Model{bg:cornsilk],  
24 | [Cart|order;cartLines]1++-0..*>[CartLine]
25 | 
26 | ![Cart Cartline model](manuscript/images/model/cart-cartline.png)
27 | 
28 | ### manuscript/images/model/order-orderline.png
29 | 
30 | [OrderLine|order;cartLine;purchasable]-1>[note: Purchasable Model{bg:cornsilk],  
31 | [Order|cart;orderLines]<1-0..*>[OrderLine]
32 | 
33 | ![Order Orderline model](manuscript/images/model/order-orderline.png)
34 | 
35 | ### manuscript/images/model/product-component.png
36 | 
37 | [Variant|product;values],
38 | [Value|attribute],
39 | [Purchasable]^-[Product],
40 | [Purchasable]^-[Variant],
41 | [Product]1++-*>[Variant],
42 | [Variant]<*-*>[Value],
43 | [Attribute]<1-*>[Value]
44 | 
45 | ![Product component model](manuscript/images/model/product-component.png)
46 | 
47 | ### manuscript/images/model/category.png
48 | 
49 | [Category|subCategories;parent;products],
50 | [Category]<1-*>[Category],
51 | [Category]<*-*>[Product]
52 | 
53 | ![Category model](manuscript/images/model/category.png)
54 | 


--------------------------------------------------------------------------------