On twitter today I tweeted the following:

https://twitter.com/ashsmithco/status/1177996134322708490 

Yep. I found a way of reducing a 799mb `pub/static` directory in Magento to just __80mb__. I was a little shocked.

In this example, we have 7 frontend themes and 4 locales. So that's 28 directories containing a lot of duplicated files. Additionally, we have 2 locales used on the adminhtml theme.

After running a few tests, I can confirm it works, and without any pitfuls that I can foresee!

All you'll need to do is to install `rdfind`, and run `rdfind -makehardlinks true  pub/static`. Integrate this with your CI/CD pipeline, and you'll be saving plenty of disk space, but also network transfer too.

This has massive value when you're trying to keep Docker image sizes down. My Magento image went from 509MB to 245MB (when compressed). That's reduced its size by over half!

#### How does this sourcery work!?

`rdfind` will search all files in the given path, check their contents, and find duplicates, and then with the `-makehardlinks true` flag set it will replace duplicates with hard links.

It uses an algorithm to do it effectively, and you can read more here: [https://github.com/pauldreik/rdfind](https://github.com/pauldreik/rdfind)

#### So what are hard links?

Wikipedia says the following:

> In computing, a hard link is a directory entry that associates a name with a file on a file system. All directory-based file systems must have at least one hard link giving the original name for each file. The term “hard link” is usually only used in file systems that allow more than one hard link for the same file.

Effectively what is happening is we have multiple files that have a 'hard link' to the same inode, or same file that is written to the disk.

Hard links have some limitations:

- You can't use them on directories on most operating systems.
- You can't use them across volumes.

If you'd prefer to use a soft link (or symlink) rdfind also supports this.

#### With great power...

Use this cautiously, and sparingly. In the case of Magento it makes sense to be using this on the `pub/static` directory for a production mode website *after* static content has been compiled/deployed. These files shouldn't be written to again, and your next deployment you'll be recreating those directories anyway.

Plus if you're running `bin/magento setup:static-content:deploy` as part of your CI process, you'll always have a clean filesystem to run `rdfind` in.

Optimising Magento 2's pub/static directory size

Lately I've been working on a few customisations to Magento 2 by introducing new API endpoints using the webapi functionality. A disucssion at work was then sparked regarding how Magento actually handles different response codes in the webapi. How can I trigger a 400, 401, 500 for exmaple? So, I dug into it to find out more.

TL;DR; It turns out, it all depends on the type of Exception that your code throws.

Before I dive into exactly what Exceptions do what, let's quickly dive into where this logic is, and how I found it.

To track this down, I already knew that all api calls go via `/rest/[your-endpoint]`, so this means there is a Controller! That controller is here: https://github.com/magento/magento2/blob/2.3-develop/app/code/Magento/Webapi/Controller/Rest.php

Inside of the `dispatch` method you'll see this try/catch block:

```php
try {
    $processor = $this->requestProcessorPool->getProcessor($this->_request);
    $processor->process($this->_request);
} catch (\Exception $e) {
    $maskedException = $this->_errorProcessor->maskException($e);
    $this->_response->setException($maskedException);
}
```

The key line here, is the two lines in the catch statement. It's the `$maskedException` that has handled all the logic behind what will be returned on the response in terms of status code, and messages to the user.

Now let's dive into the error processor. This can be found here: https://github.com/magento/magento2/blob/2.3-develop/lib/internal/Magento/Framework/Webapi/ErrorProcessor.php

The `maskException` method contains a lot of logic to figure out what status codes to use, and wether or not to hide the original exception from the end user.

Esentially it boils down to this:

- If it's an instance of `Magento\Framework\Webapi\Exception` (aliased as `WebapiException`) return that. This Exception class requires you to define a status code to be returned, along with other parameters.
- Instances of `Magento\Framework\Exception\LocalizedException` are handled slightly differently.
 - `NoSuchEntityException` will return a 404 (doesn't exist)
 - `AuthorizationException` or `AuthenticationException` will return 401
 - Any other instance of a `LocalizedException` will be a 400.
- Any other exception will be masked, and hidden from the end user.


With this information, you can see we have a fair amount of flexability. For example, if the error codes returned by an instance of a `LocalizedException` doesn't suit your requirements, then you just need throw a `Magento\Framework\Webapi\Exception` with the desired response code that you require.

👌

Understanding Magento 2's webapi exception handling


If you ever need to programmatically add a class to the body tag of your Magento stores, you’ll need to setup an event observer for the `layout_load_before` event. Within your observer you’ll then want to add `Magento\Framework\View\Page\Config`  as a dependency, you’ll then use the `addBodyClass` method to add your class.

See below for a more detailed example. In my example, I’m adding the class `customer-logged-in` to the body when a customer is logged in.

**Event:** `layout_load_before`

**File:** `etc/frontend/events.xml`
```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="layout_load_before">
        <observer name="vendor_module_add_body_class" instance="Vendor\Module\Observer\AddClassToBody" />
    </event>
</config>
```

**File:** `Observer/AddClassToBody.php`
```php
<?php
namespace Vendor\Module\Observer;

use Magento\Customer\Model\Session as CustomerSession;
use Magento\Framework\View\Page\Config as PageConfig;
use Magento\Framework\Event\ObserverInterface;

class AddClassToBody implements ObserverInterface
{
    /** @var PageConfig */
    protected $pageConfig;
	  /** @var CustomerSession */
    protected $customerSession;

    public function __construct(PageConfig $pageConfig, CustomerSession $customerSession)
    {
        $this->pageConfig = $pageConfig;
        $this->customerSession = $customerSession;
    }

    public function execute(\Magento\Framework\Event\Observer $observer)
    {
        if (!$this->customerSession->isLoggedIn()) {
            return;
        }

        $this->pageConfig->addBodyClass('customer-logged-in');
    }
}

```


**Tip:** Some class names in Magento are not very help when you’re using the `use`  statement. I’ll often use an alias to refer to classes see below:

**Example:**

Directly using `Magento\Customer\Model\Session` in my constructor is long winded. But also, when using the `use` statement simply putting `Session` doesn’t mean too much either.

Instead I’ll do this: `use Magento\Customer\Model\Session as CustomerSession;`. Immediately it’s clear what the class is doing.

Another example: `use Magento\Framework\View\Page\Config as PageConfig;`. `Config` doesn’t mean anything useful, however `PageConfig` is much more meaningful as it provides that extra bit of context into what the class does.




Programmatically adding a class to the page body

I was googling around how to add a form key to my form today, and posts out there were telling me to use the ObjectManager. Which is a terrible idea. So, here’s the right way.

Trying to figure out how to add a form key to your form? You’ll need to add `Magento\Framework\Data\Form\FormKey`  class as a dependency to your Block, and get the form key from the method `getFormKey()`.

Here’s a practical example:

```php
<?php
namespace Namespace\Module\Block;

use \Magento\Framework\View\Element\Template;
use \Magento\Framework\View\Element\Template\Context;
use \Magento\Framework\Data\Form\FormKey;

class MyBlock extends Template {

    protected $formKey;

    public function __construct(FormKey $formKey, Context $context, array $data = []) 
    {
        $this->formKey = $forKey
        parent::__construct($context, $data);
    }

    public function getFormKey()
    {
         return $this->formKey->getFormKey();
    }

}
```

Then in your template you’ll be able to use it like so:

```html
<?php /** @var $block \Namespace\Module\Block\MyBlock */ ?>
<form action="/myform" method="post">
    <input type="hidden" name="form_key" value="<?php echo $block->getFormKey() ?>" />
    
</form>
```

If you’re new to adding classes as dependencies, and want to learn more check out: [Dependency injection - Magento 2 Developer Documentation](http://devdocs.magento.com/guides/v2.0/extension-dev-guide/depend-inj.html)

Equally, learn about why another approach that uses the ObjectManager is a terrible idea: [ObjectManager - Magento 2 Developer Documentation](http://devdocs.magento.com/guides/v2.0/extension-dev-guide/object-manager.html)

Until next time.

Getting a form key for your form.


Sometimes you’ll need to get the add to cart URL for a given product, to do this you’ll want to use the following helper class: `Magento\Checkout\Helper\Cart`, and the method: `getAddUrl`.

Below is a practical example of this being used:


```php
<?php
namespace Namespace\Module\Block;

use \Magento\Framework\View\Element\Template;
use \Magento\Framework\View\Element\Template\Context;
use \Magento\Checkout\Helper\Cart as CartHelper;
use \Magento\Catalog\Api\ProductRepositoryInterface;

class MyBlock extends Template {

    protected $cartHelper;
    protected $productRepository;

    public function __construct(CartHelper $cartHelper, ProductRepositoryInterface $productRepository Context $context, array $data = []) 
    {
        $this->cartHelper = $cartHelper;
        $this->productRepository = $productRepository;
        parent::__construct($context, $data);
    }

    public function getAddToCartUrlForProduct($productSku)
    {
        $product = $this->productRepository->get($productSku);
        return $this->cartHelper->getAddUrl($product);
    }

}
```


Don’t forget that any similar examples using the ObjectManager are bad practise and should be avoided.

Final note: When you use this URL, make sure you submit it with a POST request, and that the request [contains the form key too](/magento2/tip-getting-a-form-key-in-your-template/)!

Getting the add to cart URL for a product.


I was googling around how to get a formatted price today, and posts out there were telling me to use the ObjectManager. Which is a terrible idea! So, here’s the right way.

If you ever need to retrieve a formatted price, with the currency attached in Magento 2 the best way of doing this by adding the class as a dependency to your own the class. The class we need to add as a dependency is: `Magento\Framework\Pricing\Helper\Data` 

This helper class has two methods to use. The `currency` method or `currencyByStore` method. The `currency` method will use the current store scope’s currency. `currencyByStore` works in the same way by default, but has a second optional parameter to define which store.

Method signatures:

```php
currency($value, $format = true, $includeContainer = true)

currencyByStore($value, $store = null, $format = true, $includeContainer = true)
```

*Tip:* Setting the  `$includeContainer` parameter value to `false` will remove containing html, and you’ll just get the price and it’s currency.

How do you add a class to your class you ask? Simple, we pass it as an argument into our `__construct`, then set the instance to a protected property on the class. See the example below:

```php
<?php
namespace Namespace\Module\Model;

class MyClass {

    protected $pricingHelper;

    public function __construct(Magento\Framework\Pricing\Helper\Data $pricingHelper) 
    {
        $this->pricingHelper = $pricingHelper
    }

    public function getFormattedPrice($price, $format = true, $includeContainer = true)
    {
         return $this->pricingHelper->currency($price, $format, $includeContainer);
    }

}
```

It’s possible you’ve come across ObjectManager examples. These are BAD practices. Always do the extra work to inject your classes correctly, don’t get lazy! The Dependency Injection system is better in the long run, as your dependencies are made clear. 

Read more about why ObjectManage is not recommended [ObjectManager - Magento 2 Developer Documentation](http://devdocs.magento.com/guides/v2.0/extension-dev-guide/object-manager.html) (better yet, its straight from the horses mouth)

Seeing ObjectManager examples everywhere drove me to write this post.

Formatting a price with the currency symbol.


Recently needed to add custom images to the media gallery, and below are the two approaches I investigated. 

First of all, lets look how to do this in Javascript, as this seemed like a good way of going about it. By modifying the media gallery widget we can update the gallery images fairly easily:

```html
<script>
    require(['jquery'], function ($) {
        var gallerySelector = '[data-gallery-role=gallery-placeholder]';
        $(gallerySelector).on('gallery:loaded', function () {
            var gallery = $(gallerySelector).data('gallery');
            var images = gallery.returnCurrentImages();
            images.push({
                img: 'image1.jpg',
                thumb: 'thumb1.jpg',
                full: 'full1.jpg',
                caption: 'caption',
                position: 100
            });
            gallery.updateData(images);
        });
    });
</script>
```

This works quite nicely. But to be honest, I’d prefer the images to be added to the gallery in PHP code rather than in JS, because it’ll have less of a performance impact.

So let’s take a look at my second, and final approach:

I used a plugin after `getGalleryImages` is called on the Gallery block class: `Magento\Catalog\Block\Product\View\Gallery`. All we’ll need to do is add our image data to the collection that `getGalleryImages` returns. Simple as that.

File: `di.xml`
```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
	<type name="Magento\Catalog\Block\Product\View\Gallery">
        <plugin name="add_images_to_gallery" type="VENDOR\MODULE\Plugin\AddImagesToGalleryBlock" />
    </type>
</config>
```

File: `Plugin/AddImagesToGalleryBlock.php`
```php
<?php
namespace VENDOR\MODULE\Plugin;

use Magento\Catalog\Helper\Image;
use Magento\Catalog\Model\Product;
use Magento\Framework\App\Filesystem\DirectoryList;
use Magento\Catalog\Block\Product\View\Gallery;

class AddImagesToGalleryBlock
{
    protected $dataCollectionFactory;
    protected $filesystem;
    protected $mediaConfig;
    protected $imageHelper;
    protected $dataCollectionFactory;

    public function __construct(
        \Magento\Framework\Data\CollectionFactory $dataCollectionFactory,
        \Magento\Framework\Filesystem $filesystem,
        \Magento\Catalog\Model\Product\Media\Config $mediaConfig,
        Image $imageHelper,
        \Magento\Framework\Data\CollectionFactory $dataCollectionFactory
)
    {
        $this->dataCollectionFactory = $dataCollectionFactory;
        $this->filesystem = $filesystem;
        $this->mediaConfig = $mediaConfig;
        $this->imageHelper = $imageHelper;
        $this->dataCollectionFactory = $dataCollectionFactory;
    }

    /**
     * @param Gallery $subject
     * @param \Magento\Framework\Data\Collection|null $images
     * @return \Magento\Framework\Data\Collection|null
     */
    public function afterGetGalleryImages(Gallery $subject, $images) {
        $product = $subject->getProduct();
        if (!$images instanceof  \Magento\Framework\Data\Collection) {
            $images = $this->dataCollectionFactory->create();
        }

       
        $myCustomImages = $product->getExtensionAttributes()->getCustomImages();
        if (empty($myCustomImages)) {
            return $images;
        }

        $directory = $this->filesystem->getDirectoryRead(DirectoryList::MEDIA);

        $imageId = uniqid();
        $imageCount = $images->getSize();
        $myCustomImage = '/s/o/some_image.jpg';
        $file = $myCustomImage;
        $smallImage = $this->imageHelper->init($product, 'product_page_image_small')
            ->setImageFile($file)
            ->getUrl();
        $mediumImage = $this->imageHelper->init($product, 'product_page_image_medium')
            ->constrainOnly(true)->keepAspectRatio(true)->keepFrame(false)
            ->setImageFile($file)
            ->getUrl();
        $largeImage = $this->imageHelper->init($product, 'product_page_image_large')
            ->constrainOnly(true)->keepAspectRatio(true)->keepFrame(false)
            ->setImageFile($file)
            ->getUrl();
            
        $image = [
            'file' => $file,
            'media_type' => 'image',
            'value_id' => $imageId, // unique value
            'row_id' => $imageId, // unique value
            'label' => 'some image',
            'label_default' => 'some image',
            'position' => 100,
            'position_default' => 100,
            'disabled' => 0,
            'url'  => $this->mediaConfig->getMediaUrl($file),
            'path' => $directory->getAbsolutePath($this->mediaConfig->getMediaPath($file)),
            'small_image_url' => $smallImage,
            'medium_image_url' => $mediumImage,
            'large_image_url' => $largeImage
        ];
        $images->addItem(new \Magento\Framework\DataObject($image));

        return $images;
    }
}

```


*Side note:* you can see I used the product image helper (`$this->imageHelper`) to fetch the small, medium and large images. This is because the images I’m using are actually stored in the product media (`pub/media/catalog/product`) directory, and it seemed like a good idea to stick to Magento’s image resizing without any additional customisations.

I hope this article points you in the right direction to adding images to the media gallery! 

Adding custom images to the product media gallery.

After attending [MageTitans MCR](https://twitter.com/MageTitans) it was abundantly clear that UI Components are a huge pain point for a lot of people! I feel the same way, and to be honest it makes me feel like a bad developer when I struggle to do (supposedly) straight forward things and it ends up taking hours, or even days to achieve. 

Hearing the same from other developers made me realise we need to do something. I left MageTitans feeling a lot better knowing I wasn't the only one, but I also left motivated to try and figure out what could be done about it. This left me with a long train journey back down to the [land of cider](https://www.youtube.com/watch?v=lzGkB6YO9Yc) with a lot to think about.

In regards to trying to fix the problem, I believe it comes down to three core issues:

**XML Fatigue**. XML is great, but when you need to modify insanely large node trees, you'll find yourself making silly mistakes or just getting lost.

**Documentation**. There is a lack of practical examples, and sample usage of components. I have to dig through the core, and figure out on my own how to render a simplified version of a component (i.e. stripping out parents/children).

**Dev tools**. There isn't any dev tools to make the debugging of UI Components any easier, that are provided out of the box with Magento. The community efforts are great though, and I'll touch on those later. But, not everyone knows about them.

Most problems comes from the above, and subpar documentation is the biggest issue of them all.

I believe if we can tackle these three issues we can resolve most of the frustration around Magento's UI Components. Below, I'm going to break down each item a little more, and describe why it isn't working, and what we can do to resolve it.


### XML Fatigue

The very first thing that comes to mind when working with UI Components are, as [Max Pronko](https://twitter.com/max_pronko) said, [XML Christmas Trees](https://twitter.com/benmarks/status/929378725594107905). It is really difficult to find components nest this deep, and writing out all that XML is prone to error (we're all human).

So let's take a quick example of a deeply nested component, where all we want to do is replace the JS component with our own:

```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="checkout.root">
            <arguments>
                <argument name="jsLayout" xsi:type="array">
                    <item name="components" xsi:type="array">
                        <item name="checkout" xsi:type="array">
                            <item name="children" xsi:type="array">
                                <item name="steps" xsi:type="array">
                                    <item name="children" xsi:type="array">
                                        <item name="shipping-step" xsi:type="array">
                                            <item name="children" xsi:type="array">
                                                <item name="shippingAddress" xsi:type="array">
                                                    <item name="component" xsi:type="string">Ashsmith_Checkout/js/view/shipping</item>
                                                </item>
                                            </item>
                                        </item>
                                    </item>
                                </item>
                            </item>
                        </item>
                    </item>
                </argument>
            </arguments>
        </referenceBlock>
    </body>
</page>
```

And there is that Christmas tree. This likely isn't the worst example either.

The idea I had for solving this came to me on the train. It's simple. What if Magento introduced two new nodes within XML Layouts. I'd call them `alias` and `referenceAlias`. An alias would be a way of taking deeply nested nodes representing them as a string and giving it a name we can reference later in `referenceAlias` to make our changes. We'd result in writing less XML, with less depth, resulting in high readability. If Magento provided this, along with a bunch of useful aliases defined for us, they would be invaluable extension points.

Consider the following:

```xml
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        
        <alias name=checkout_step_shipping_address path=“checkout.root/arguments/jsLayout/components/checkout/children/steps/children/shipping-step/children/shippingAddress” /> 
        
        <referenceAlias name="checkout_step_shipping_address">
            
            <item name="component" xsi:type="string">Ashsmith_Checkout/js/view/shipping</item>
        </referenceAlias>
    </body>
</page>
```

The above proposed solution would be the exact same as our christmas tree, and at a glance we can see we're referencing the shipping address component. We have achieved high readability, along with reduced code. Furthermore, we would not actually introduce any breaking changes in Magento by implementing this, these are merely new extension points that can be used optionally.

Coupled with good documentation (and good alias coverage from the core), developers would be able to simple changes quickly, without too much hassle.

If you're wondering about the alias path attribute, and what makes it up, to me it takes a fairly simple approach to referencing nodes: if the node we're specifying has a name attribute, we use the name, otherwise we use the node itself. In this case see: `checkout.root/arguments/jsLayout` is actually: `<referenceBlock name=checkout.root><arguments><argument name=jsLayout>`. This will mean `referenceContainer`, `referenceBlock`, `argument`, `item` nodes are all referenced by their name attribute, and the `arguments` node has no attributes to be referenced by so we simply use the nodes name.

An alternative approach could be introduce a new (optional) attribute to the `item` node whereby we can specify this alias name. eg: `<item name="shippingAddress" alias="checkout_step_shipping_address" xsi:type="array">` then use `<referenceAlias name="">` as before. This would skip the node tree path option, but would make it impractical for developers to introduce, we'd be at the mercy of core developers. 

This approach should also apply to UI Component XML within the Admin. These are also incredibly hard to read and digest. Check out my [post on creating a blog where I cover the admin](https://www.ashsmith.io/magento2/module-from-scratch-part-5-adminhtml/) and scroll until you hit a wall of XML. Yup _that_. Which actually, is a brilliant [segway/segue](https://itunes.apple.com/us/podcast/id1300143014) to my next suggestion on reducing XML fatigure.

Splitting large XML Files.

Who in their right mind would want to open up a [446 line XML file](https://github.com/magento/magento2/blob/2.2-develop/app/code/Magento/Checkout/view/frontend/layout/checkout_index_index.xml) and make changes. Not me! 

If we split these XML layout files up, we can reduce them down to digestible chunks, then simply extend/rewrite the appropriate layout file. Within layout XML this is already possible, and something we can do today. It's simple:

checkout_index_index.xml
```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    
    <update handle="checkout_index_index_errors">
    <update handle="checkout_index_index_authentication">
    <update handle="checkout_index_index_progress_bar">
    <update handle="checkout_index_index_estimation">
    <update handle="checkout_index_index_step_shipping">
    <update handle="checkout_index_index_step_billing">
    <update handle="checkout_index_index_sidebar">
    <body>
    
    </body>
</page>
```

checkout_index_index_step_shipping.xml
```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <update handle="checkout_index_index_step_shipping_address">
    
    <body>
    
    </body>
</page>
```

checkout_index_index_step_shipping_address.xml
```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    
    <body>
        
        
    </body>
</page>
```

Immediately we break our component configuration up into digestible chunks. This makes discovery easier, as children nodes are defined at the top of the XML file, but also we'll stick with a flat directory structure for layout files and the naming conventions would be self-explanatory.

Reduce the amount of XML I need to write. Reduce the amount of XML I need to read. Ultimately, reduce the amount of thinking I have to do, and then you'll have an [happy Ash](https://i.pinimg.com/736x/2a/c7/d0/2ac7d07764cbd45af9116a62e6714ef5--ash-ketchum-pikachu.jpg).

I don't want to sound like I'm hating on XML, it's great, but when you're faced with several hundred lines of XML, I honestly can't keep track of it. You're literally going down the rabbit hole each time, and each time I lose a little more of my sanity. Keep It Simple Splease.

### Documentation (or lack thereof)

Good documentation is critical for Magento's adoption by new developers. I don't work with frameworks where documentation sucks, at least not for long, because how the heck will I ever figure it out? So why would someone new to the framework stick with Magento? They wouldn't, they'd sooner turn to alternatives that either have the docs (Shopify perhaps), or they'll turn to familiar solutions like WooCommerce (because of WordPress).

Further to this, frameworks/CMS's should make developers productive. We're here to provide solutions to our customers needs, and we shouldn't need to bend over backwards and spend days figuring out how stuff works, especially when it's stuff we're expected to work with regularly.

I don't want to rant too long, we all understand the importance of good documentation, good examples include: React, Laravel, Symfony, VueJS. They all have solid docs where I can quickly reference and do what needs to be done.

As it stands, I don't visit DevDocs that often, and when I do it rarely provides me with the answer I needed.

Coming back to UI Components. Components are re-usable and therefore they need solid documentation. Imagine a world where we could go onto any UI Component in the docs and see practical usage right there on the page. That would be amazing.

The Magento Community as a whole does a great job when it comes to blog posts, and answering questions on StackExchange etc. Which is fantastic. However, developers need a single source of truth.

As it stands documentation for existing UI Components is limited to describing the options available on a given component. Which, I have to say, it may as well not be there, because that every time I landed on the page has been useless. 

I end up turning to the core code in order to understand the component I actually need, and well, we've already been over the problem of XML fatigue.

Need an example a good vs bad docs? [Bookmarks UI Component Docs](http://devdocs.magento.com/guides/v2.2/ui_comp_guide/components/ui-bookmarks.html) vs [VueJS List Rendering Docs](https://vuejs.org/v2/guide/list.html)

We need practical usage examples, not a table of it's options.

### Developer tooling

When I dev tools, I actually mean a toolkit that is provided out of the box. 

If we had something similar to the template hints functionality that would enable us to quickly figure out what template, which JS file, and any other useful context, then I'd be incredibly happy.

Alternatively, a JS debugging tool that is added to the page when we enable it via the command line would be great too. It just needs to be a nice wrapper around using pure Knockout, and the uiRegistry and a sprinkle of jQuery in order to help us get useful information out quickly. Consider the following:

```js
> uiDebugger.get(jQuery('#someKnockoutComponentElement'))
{
    name: 'myknockoutcomponent'
    componentClass: 'Magento_Checkout/js/view/address/checkbox',
    template: 'Magento_Checkout/address/checkbox',
    config: { ... }
    parent: 'parentname',
    children: [ ... ]
}
```

That right there would saves us from using pure Knockout to get context, and then dig through the uiRegistry to gather additional information. In more advanced instances you You could provide useful functions to return that pure data, such as `getRawKnockoutContext()` or `getRawUIRegistryContext()`.

If you're looking for something to use today:

- [KnockoutJS Chrome extension](https://chrome.google.com/webstore/detail/knockoutjs-context-debugg/oddcpmchholgcjgjdnfjmildmlielhof?hl=en)
- [MageSpecialist DevTools Chrome Extension](https://chrome.google.com/webstore/detail/magespecialist-devtools-f/odbnbnenehdodpnebgldhhmicbnlmapj) - Thanks to [Maria Kern](https://twitter.com/maja_kern)'s talk at MageTitans for pointing this one out!

The KnockoutJS debugger is great, but it'll be limited in regards to Magento's UI Components in terms of useful information. The MageSpecialist DevTools extension on the other hand provides a huge amount of context in much easier to use format.

We do have some documentation already on using the KnockoutJS extension, and also a little on taking advantage of uiRegistry. But organisation of the docs makes it tricky to figure out how it works.

Example from dev docs below, there was no context on how/where the registry name came from (it comes from having to use the KnockoutJS context...)

```js
// Admin > Products > Catalog > Add Product
var fieldName = registry.get('product_form.product_form.product-details.container_name.name');
```


## What happens next?

I intend on suggesting my XML changes to Magento, I also want your feedback. Maybe it's just me who thinks that `alias`, `referenceAlias`, and utilising layout handle updates more is a good idea. Maybe there's stuff I haven't thought of.

The full technical discussion probably should happen on GitHub or on the forums, that's way an official proposal could be discussed and put forward, then PR's can go from there. 

I see them as non-breaking changes, so I can't see why it would be a bad idea. If you have an opinion on this, please reach out. I'd love to hear your thoughts and find the best solution.

I realise this alias option doesn't offer something that can be used today, and it'll be yet another thing we'd have to wait for (I also hate hearing "Oh yeah but 2.x fixes that"). 

In the meantime, we have documentation to fix, and further deep dive blog posts to write in order to help make UI Components seem like a not-so frightening task. Providing a central well-organised place for UI Component documentation should be the most actionable item though.

I want to do my part. I find myself working with UI Components regularly, and I'd like to write up what I've learnt (provided I don't over-commit and under deliver!). I already have plans for a deeper dive into Admin UI Components, along with some practical frontend component changes/implementation examples. Perhaps some of this could be ported over to the devdocs.

Finally, we need to keep the conversation going. I'm on [twitter](https://twitter.com/ashsmithco), there's the comments below this post, and my inbox welcomes you too (use the <a href="https://www.urbandictionary.com/define.php?term=gert">gert</a> big contact me link below this post).

PS, keep an eye out for videos from [MageTitans MCR](https://twitter.com/MageTitans) there were two fantastic talks touching on UI Components which will help you out massively. For me, [Maria Kern](https://twitter.com/maja_kern)'s talk mentioned a few useful Chrome extensions such as [MageSpecialist DevTools](https://chrome.google.com/webstore/detail/magespecialist-devtools-f/odbnbnenehdodpnebgldhhmicbnlmapj) which will give you information on UI Components. I honestly can't wait to try this out on Monday.

I feel like I should finish this with some sort of statement we can all get behind...

"Make UI Components Great Again". Yeah, that'll do.

[This too.](https://twitter.com/philwinkle/status/929093121174134784)

Sorry for the long post. Sorry if I ranted, or badly written in places. I was tired when I wrote this, I woke up tired when I proof read this, and rest of my day is being spent working on UI Components. (Yes, I am trying to get sympathy here).

Suggestions for improving UI Components in Magento 2


In today’s post I’m going to go over how I create custom attributes for products. I will be creating a standalone module that will create my desired product attribute, and we handle how data is saved and fetched from the attribute.

In this tutorial I’ll be creating a “features” attribute. It will simply be a text area attribute, where the admin can define the products features via an unordered list.

## Step 1) Create our module

I’m using n98-magerun2 for generating my module, so I won’t post all the initial code for this, but this command gives us the boilerplate we’d like:

```bash
n98-magerun2.phar dev:module:create --add-setup --add-readme --add-composer --author-name="Ash Smith" --author-email="hello@ashsmith.io" Ashsmith ProductFeatures
```

# Step 2) Create our InstallData class
Our InstallData class handle the creation of our new `features` attribute:

```php
<?php

namespace Ashsmith\ProductFeatures\Setup;

use Magento\Framework\Setup\InstallDataInterface;
use Magento\Framework\Setup\ModuleContextInterface;
use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Eav\Setup\EavSetupFactory;
use Magento\Catalog\Model\Product;

class InstallData implements InstallDataInterface
{
    /**
     * @param EavSetupFactory $eavSetupFactory
     */
    public function __construct(EavSetupFactory $eavSetupFactory)
    {
        $this->eavSetupFactory = $eavSetupFactory;
    }

    public function install(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
    {
        $setup->startSetup();

        /** @var \Magento\Eav\Setup\EavSetup $eavSetup */
        $eavSetup = $this->eavSetupFactory->create(['setup' => $setup]);

        // Add our "features" attribute
        $eavSetup->addAttribute(Product::ENTITY, 'features', [
            'type' => 'text',
            'label' => 'Features',
            'input' => 'textarea',
            'required' => false,
            'sort_order' => 100,
            'global' => \Magento\Eav\Model\Entity\Attribute\ScopedAttributeInterface::SCOPE_STORE,
            'wysiwyg_enabled' => true,
            'is_html_allowed_on_front' => true,
        ]);

        $setup->endSetup();
    }
}
```

This class contains two methods `__construct` and `install`. Let’s walk through them quickly.

In the `__construct` we are injecting our only dependency. The `Magento\Eav\Setup\EavSetupFactory` class. We require this class in order to create EAV attributes.

Meanwhile the `install` is required by `InstallDataInterface`, this is the public method that will be executed when our module is installed. Within here we run `$setup->startSetup()` (remember that from Magento 1? It does the same thing, disables foreign key constraint.). Then we create our attribute. Finished off with `$setup->endSetup()` which enables foreign key constraints again.

Let’s discuss the attribute settings

```php
[
    'type' => 'text',
    'label' => 'Features',
    'input' => 'textarea',
    'required' => false,
    'sort_order' => 100,
    'global' => \Magento\Eav\Model\Entity\Attribute\ScopedAttributeInterface::SCOPE_STORE,
    'wysiwyg_enabled' => true,
    'is_html_allowed_on_front' => true,
]
```

The `type` key informs us which which EAV table this attributes data will saved to. In this case it’s `catalog_product_entity_text`. 

`label` is a user friendly label that is used within the admin (and can be used on the frontend too).

 `input` defined the type of input that will be used, so in our case we’re going for a `textarea` as I want people to write multiple lines. 

`required` is a boolean value, which tells us if the field is required to be entered before the product can be saved.

`sort_order` defines the order it will be displayed within the admin.

`global` tells us the scope that is allowed for the value to be modified. In this case I have defined it to the store scope, which means you can override this value on specific store views if you wish. Other options are: website (you can override a website level at most), global (can only be defined on the global scope).

`wysiwyg_enabled` is a boolean that will make the WYSIWYG editor display for this particular attribute. Allowing admin users to use a GUI style interface instead of authoring raw HTML.

`is_html_allowed_on_front` tells the validation engine that HTML is allowed for this attribute. This is important as we’d like to render the HTML!

## Step 3) Install our module and test the attribute exists!

Next up, we’ll need to enable our module and install the data.

```bash
bin/magento module:enable Ashsmith_ProductFeatures
bin/magento setup:upgrade
```

Once this has run, we can head to the admin and modify an existing product (or create a new one), and you’ll now find your new attribute!

Ok great. Now how do we use it on the frontend? Let’s move on to that now!

## Step 4) Define our configuration in extension_attributes.xml and di.xml

The first step is to register our extension attribute with Magento 2. We do this like with `extension_attributes.xml` which lives within the `etc` directory of your module.

`etc/extension_attributes.xml`

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Api/etc/extension_attributes.xsd">
    <extension_attributes for="Magento\Catalog\Api\Data\ProductInterface">
        <attribute code="features" type="string" />
    </extension_attributes>
</config>
```

Note: `<extension_attributes for=“CLASS”>`? This tells Magento 2 which class we are defining an extension attribute for. As we’re doing this for a product, we’ll need to use the `Magento\Catalog\Api\Data\ProductInterface` interface.

The next line `<attribute code=“” type=“” />` defines our attributes. We give them a name, and a type. The `type` in this case can reference either a PHP type or a class type.

Next up is our `di.xml` again, living in `etc` directory. This is so we can register a plugin to set data to our extension attribute (I’ll cover this more in the next step)

`etc/di.xml`

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Catalog\Api\ProductRepositoryInterface">
        <plugin name="get_product_features" type="Ashsmith\ProductFeatures\Plugin\ProductGet"/>
    </type>
</config>
```
 
In our di.xml we have defined a plugin for the `ProductRepositoryInterface`. Our plugin class is: `Ashsmith\ProductFeatures\Plugin\ProductGet` we’ll need to create this in the next step.

## Step 5) Create our plugin

Now, when creating extension_attributes you can implement your own logic. Thats one of the powerful features of extension_attributes. Instead of defining a PHP type you could instead specify a class that implements a bunch of logic. However, the drawback is if you’re implementing something “simple” like an attribute in our case, we still need to do all the hard work. No magic here folks.

The way we achieve this is by defining a plugin around the `getById` method on the `ProductRepositoryInterface` interface. At this point we can handle fetching data directly from the product model, and set it on the extension attribute class.

```php
<?php namespace Ashsmith\ProductFeatures\Plugin;

use Magento\Catalog\Api\Data\ProductInterface;

class ProductGet
{
    protected $productExtensionFactory;
    protected $productFactory;

    public function __construct(
        \Magento\Catalog\Api\Data\ProductExtensionFactory $productExtensionFactory,
        \Magento\Catalog\Model\ProductFactory $productFactory
    )
    {
        $this->productFactory = $productFactory;
        $this->productExtensionFactory = $productExtensionFactory;
    }

    public function aroundGetById(
        \Magento\Catalog\Api\ProductRepositoryInterface $subject,
        \Closure $proceed,
        $customerId
    )
    {
        /** @var ProductInterface $product */
        $product = $proceed($customerId);

	// If extension attribute is already set, return early.
        if ($product->getExtensionAttributes() && $product->getExtensionAttributes()->getFeatures()) {
            return $product;
        }

        // In the event that extension attribute class has not be instansiated yet.
        // in this event, we create it ourselves.
        if (!$product->getExtensionAttributes()) {
            $productExtension = $this->productExtensionFactory->create();
            $product->setExtensionAttributes($productExtension);
        }

        // Fetch the raw product model (I have not found a better way), and set the data onto our attribute.
        $productModel = $this->productFactory->create()->load($product->getId());
        $product->getExtensionAttributes()
            ->setFeatures($productModel->getData('features'));

        return $product;
    }
}
```

## Step 6)  Creating a Block and template

To finish this off, let’s create a quick Block and template to test all of this.

Create: `Block/Features.php`
Here we’re extending `Magento\Catalog\Block\Product\View` this gives us access to the current product with ease.

```php
<?php
namespace Ashsmith\ProductFeatures\Block;

use Magento\Catalog\Block\Product\View;

class Features extends View
{
    public function getFeatures()
    {
        return $this->getProduct()->getExtensionAttributes()->getFeatures();
    }
}
```

Create: `view/frontend/template/product_features.phtml`

```php
<?php /** @var $block Ashsmith\ProductFeatures\Block\Features */ ?>
<div class="product-view-features">
    <h4><?php echo __("Features:") ?></h4>
    <?php echo $block->getFeatures(); ?>
</div>
```

Create: `view/frontend/layout/catalog_product_view.xml`

```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Ashsmith\ProductFeatures\Block\Features" name="product.info.features"
                   after="product.info.details"
                   template="Ashsmith_ProductFeatures::product_features.phtml"/>
        </referenceContainer>
    </body>
</page>
```

## Step 7) Give it a test drive!
Now we can flush cache, and head to a product. With a little luck we’ll have our features displaying on the page.

Side note: I didn’t implement any logic to hide the features when none are set to keep this simple.

## Magento 2 extension attribute gotchas.
Please, please use developer mode: `bin/magento deploy:mode:set developer`. Whilst writing this article I did not need to re-compile DI (despite what you may think. I promise. Developer mode is the reason for this.)

## Bonus. Add some less
Nothing fancy. But I’d like to bump up the font size, make ‘em bold and spread ‘em out a bit.

You can add LESS to your modules by creating a `_module.less` file:

`view/frontend/web/css/source/_module.less`

```less
.product-view-features {
    li {
        font-size: 1.2em;
        font-weight: bold;
        line-height: 2em;
    }
}
```



Using Extension Attributes in Magento 2 on Products


As with any new platform, you’ll want to learn how to be as efficient as possible so that you can get more done and avoid common pitfalls. This happens over time as you learn any platform. I’d like to share with you a few tips that can help you become more productive. They certainly helped me.

## 1. Developer mode.
Developer mode is critical when doing development (it sounds so obvious…). Running in the default or production modes will slow you done ten fold. Whilst Magento 2 is in developer mode everything in `pub/static` is symlinked, which means as you update the files in their source location, it’ll update in `pub/static`.

```bash
bin/magento deploy:mode:set developer
```

You can use: `bin/magento deploy:mode` to see what mode you’re currently running in. When switching modes Magento 2 will automatically handle any cleanup required. So when switching from default or production to developer mode it will delete the contents of `pub/static` and the `var/` appropriate directories.

## 2. Use Grunt.
Whilst  a lot of the frontend world have moved towards using Gulp, Grunt is still a great tool to use for frontend development. Let’s not get hung up on that, and focus on how we can use it to enhance our productivity.

#### Set up Grunt with:
```bash
mv Gruntfile.js.sample Gruntfile.js
mv package.json.sample package.json
npm install -g grunt-cli
npm install
```

#### Configure Grunt

You’ll want to configure Grunt by adding your theme to `[magento-root]/dev/tools/grunt/configs/themes.js`, use an existing theme in the file as your template.

#### Using Grunt in Magento 2

Once you have grunt setup, there are a few commands you can use to speed up your workflow.

```bash
# compile less for your theme
grunt less:<theme>

# removes theme related static files from pub/static and var
grunt clean:<theme>

# republish theme symlinks for your theme to pub/static
grunt exec:<theme>

# tracks changes to source files, recompiles less, and reloads page when using BrowserSync
grunt watch
```

Note the last one and the usage of browser sync. We’ll visit that in our next tip.

Learn more about the grunt commands from Magento’s DevDocs: [Compile LESS with Grunt](http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/css-topics/css_debug.html)

## 3. Use BrowserSync
BrowserSync is a great tool for automatically injecting new css into your browser each time it is updated. It’s pretty simple to use.

First, start the `grunt watch` task in a terminal window.

```bash
grunt watch
```

Next, open up a second terminal window and install browser sync if you haven’t already:

```bash
npm install -g browser-sync
```

Next, change to your `css` directory within `pub/static` e.g:

```bash
cd pub/static/frontend/MyTheme/default/en_GB/css
```

Now, fire up browser-sync with the following (adjust the proxy URL to your store installation)

```bash
browser-sync start --proxy 'dev.www.mystore.com' --files="*.css"
```

This will launch a browser tab opening to: `http://localhost:3000` which will load your store. Now as you make changes to your LESS files the `grunt watch` command will re-compile the CSS, which in turn triggers browser sync to inject the new css. All without you having to lift a finger.

/Note: If you’re using docker, I currently run browser-sync outside of docker, and grunt runs inside. It works great./

## 4. Overriding templates and LESS.

After overriding templates and LESS files, you’ll want to flush cache and recompile LESS. Here’s some quick commands to make your life a little easier:

```bash
bin/magento cache:flush layout block_html full_page
grunt clean:<theme>
```

This will ensure the `block_html` `layout`  and `full_page` cache types have been flushed. These are the most critical, and most likely to get in the way during frontend development. You could also disable these, but I prefer not to. If you’re making changes that could effect other cache types such as configuration (`config` type), then be sure to flush those too.

## Bonus tip: Read the docs.
Seriously. READ them. I’m terrible for scan reading and just trying to find the snippet I need. But when you actually take time to read the documentation you’ll find a lot of topics are covered and well explained.

Documentation I’ve found useful:
1. [Compile LESS with Grunt](http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/css-topics/css_debug.html)
2. [Common layout customization tasks](http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/layouts/xml-manage.html)
3. [CSS preprocessing](http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/css-topics/css-preprocess.html)
4. [Override a layout](http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/layouts/layout-override.html)
5. [Locate templates, layouts, and styles](http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/themes/debug-theme.html)

## Conclusion
With these five tips you can speed up your frontend development workflow, and become a more productive Magento 2 developer as a result. As someone who is more commonly associates himself as a back-end developer, these tips are something I need to remind myself of, and have worked their way into my daily workflow.

Have you got any tips? Let me know in the comments!


4 tips for a more productive Magento 2 Frontend Workflow


In this blog post I aim to cover a number of topics surrounding transactional emails. Such as:

- Overview of how transactional emails are built up in Magento 2.
- Using that information to create and send our own.
- How to replace the default email transport method with an external service

Let's dive in...

## How transactional emails are built up Magento 2

There are a number of core modules we can look at for examples of how transactional emails are handled within Magento 2. The two examples I'll provide here is the `module-contact`, and `module-sales` modules. `module-contact` is a much simpler example, so we'll start here. If you're familiar with Magento 1.x, then this will be easy to get your head around!

### Contact form example

To find the `module-contact` module, head to: `vendor/magento/module-contact`.

The logic for sending emails is handled directly in the Post controller action: `Controller/Index/Post.php`.

The notable code is here:

```php
<?php
$transport = $this->_transportBuilder
    ->setTemplateIdentifier($this->scopeConfig->getValue(self::XML_PATH_EMAIL_TEMPLATE, $storeScope))
    ->setTemplateOptions(
        [
            'area' => \Magento\Backend\App\Area\FrontNameResolver::AREA_CODE,
            'store' => \Magento\Store\Model\Store::DEFAULT_STORE_ID,
        ]
    )
    ->setTemplateVars(['data' => $postObject])
    ->setFrom($this->scopeConfig->getValue(self::XML_PATH_EMAIL_SENDER, $storeScope))
    ->addTo($this->scopeConfig->getValue(self::XML_PATH_EMAIL_RECIPIENT, $storeScope))
    ->setReplyTo($post['email'])
    ->getTransport();

$transport->sendMessage();
```

In our constructor the `$_transportBuilder` property is the following class: `\Magento\Framework\Mail\Template\TransportBuilder`, and the `$_scopeConfig` must implement: `\Magento\Framework\App\Config\ScopeConfigInterface`.

This might feel familiar if you're coming from Magento 1.x background, you can see values are pulled from configuration (which email template, sender and recipient are all defined from config), template variables are passed in, and the email is sent. Pretty straight forward stuff.

Let's look at how this is done when placing an order...

### Order confirmation email example

This example is a lot more complicated, as there are a range of classes used. I'll list them out below so you can reference them easily:

- `Magento\Sales\Model\EmailSenderHandler` - This handles sending emails on cron for Orders, Invoices, Shipments or Creditmemos.
- `Magento\Sales\Model\Email\SenderBuilder` - Sends an email, and can send copies.
- `Magento\Sales\Model\Email\Sender` - Prepares and invokes `SenderBuilder`
- `Magento\Sales\Model\Email\Sender\OrderSender` - Inherits from `Sender,` but adds the public method `send`. This excepts an `Order` object, based on configuration it will either send the email immediately, or it'll allow the cron to pick up the sending.
- `Magento\Sales\Observer\Virtual\SendEmails` - Invokes `EmailSenderHandler`.

## Replacing email transport method

Magento 2 makes it incredibly easy to replace functionality with your own. With this, here is, very quickly, how to replace the default method of sending emails (sendmail), with another method.

Two use cases for replacing the default method: Debugging email templates easily (dump emails to a file in a specified folder), using an external mail service (like SendGrid, or AWS SES).

To do this, we simply need to implement the following interface: `Magento\Framework\Mail\TransportInterface`. This expects a public method `sendMessage` that accepts no parameters.

Then in your `di.xml` you will need to specify the preference:

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="Magento\Framework\Mail\TransportInterface" type="[YOUR CLASS GOES HERE]" />
</config>
```

Yes, it's that easy.

Thanks for reading! Any questions, please leave a comment below!


Transactional Emails in Magento 2



After much delay, the final installment of creating a magento 2 module from scratch I will touch on unit testing, and how Magento go about it. In terms of the module we have created so far,
we are using core magento functionality, which will already be heavily tested. So you may get the impression some of these tests aren't beneficial. However, the purpose of
this article is to give you a quick primer on how unit testing works in Magento.

## Running unit tests in Magento

To get started we can refer to the [documentation provided](http://devdocs.magento.com/guides/v2.0/config-guide/cli/config-cli-subcommands-test.html) by Magento.

You can see that we can use `bin/magento` to run our unit tests:

```bash
bin/magento dev:tests:run [--all] <test>
```

With this we can run the entire test suite (yeah, it takes a very long time), or we can specify a test suite we'd like to run, such as just the unit tests (which also takes a very long time):

```bash
bin/magento dev:tests:run unit
```

For me, I prefer to use phpunit directly, this way you can apply a filter to only run your tests. Which is useful for when you are regularly running tests as you are working on a feature.

To use phpunit directly, you need head to the test directory: `[magento2-root]/dev/tests/unit`, and run the phpunit command:

```bash
phpunit
```

This will run all unit tests within Magento, as defined in the `dev/tests/unitphpunit.xml.dist`.

## Our first unit test

Okay, with this covered lets write a test, and try to run it.

Let's start by testing the getIdentities method on `Ashsmith\Blog\Block\PostView`, if you remember back to that series this method is used for uniquely caching the block for each of our blog posts.

To get started create: `Test/Unit/Block/PostViewTest.php`.

The naming convention used here is important as this will effect which tests are loaded. So be sure to always store your unit tests within the `Test/Unit` directory.

```php
<?php namespace Ashsmith\Blog\Test\Unit\Block;

class PostViewTest extends \PHPUnit_Framework_TestCase {

    public function testGetIdentities()
    {
        $this->assertTrue(false);
    }
}
```

This is our first unit test, and it will not pass. Let's see how this runs:

```bash
phpunit --filter PostViewTest
PHPUnit 4.1.0 by Sebastian Bergmann.

Configuration read from /Users/ashsmith/Sites/magento2/dev/tests/unit/phpunit.xml.dist

F

Time: 13.17 seconds, Memory: 208.00Mb

There was 1 failure:

1) Ashsmith\Blog\Test\Unit\Block\PostViewTest::testGetIdentities
Failed asserting that false is true.

/Users/ashsmith/Sites/magento2/app/code/Ashsmith/Blog/Test/Unit/Block/PostViewTest.php:35
/Users/ashsmith/.composer/vendor/phpunit/phpunit/src/TextUI/Command.php:179
/Users/ashsmith/.composer/vendor/phpunit/phpunit/src/TextUI/Command.php:132

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.
```

It worked! Let's fix this test up, and actually test something:

```php
<?php namespace Ashsmith\Blog\Test\Unit\Block;

class PostViewTest extends \PHPUnit_Framework_TestCase {

    /**
     * @var \Ashsmith\Blog\Model\Post
     */
    protected $post;

    /**
     * @var \Ashsmith\Blog\Block\PostView
     */
    protected $block;

    /**
     * Sets up the fixture, for example, open a network connection.
     * This method is called before a test is executed.
     *
     */
    protected function setUp()
    {
        $objectManager = new \Magento\Framework\TestFramework\Unit\Helper\ObjectManager($this);
        $this->block = $objectManager->getObject('Ashsmith\Blog\Block\PostView');
        $this->post = $objectManager->getObject('Ashsmith\Blog\Model\Post');
        $reflection = new \ReflectionClass($this->post);
        $reflectionProperty = $reflection->getProperty('_idFieldName');
        $reflectionProperty->setAccessible(true);
        $reflectionProperty->setValue($this->post, 'post_id');
        $this->post->setId(1);
    }


    public function testGetIdentities()
    {
        $id = 1;
        $this->block->setPost($this->post);
        $this->assertEquals(
            [\Ashsmith\Blog\Model\Post::CACHE_TAG . '_' . $id],
            $this->block->getIdentities()
        );
    }

    /**
     * Tears down the fixture, for example, close a network connection.
     * This method is called after a test is executed.
     */
    protected function tearDown()
    {
        $this->block = null;
    }

}

```

So, our test has changed a fair bit now. Let's break it down a little:

The `setUp` method is ran _before_ every test. We also have the `tearDown` which is run _after_ every test. This allows us to setup and destroy the environment we require for our tests. In the `setUp` method we use the `TestFramework` object manager so that we can retrieve an instance of our `PostView` block and the `Post` model. We then use `ReflectionClass` to set properties on our Post model, so that the `post_id` value is defined.

Now we have two properties on our test class, `$this->block` and `$this->post`. We can now use these in our test. So if we take a look at our test: `testGetIdentities`, we set the current post on our block, and then simple assert that the getIdentities method on our block matches our expected output which is the cache tag with the post id appended.

We can run our test again and see that it passes successfully:

```bash
phpunit --filter PostViewTest
PHPUnit 4.1.0 by Sebastian Bergmann.

Configuration read from /Users/ashsmith/Sites/magento2/dev/tests/unit/phpunit.xml.dist

.

Time: 13.19 seconds, Memory: 210.00Mb

OK (1 test, 1 assertion)
```

This example above is incredibly simple, and doesn't require any interaction with the database, and tests a very specific area of our code. Ideally, your unit tests will be similar, testing small portions of code, and only interacting with what you truly need.

If you want to learn more, you can use the resources I've linked to below, or if you're looking for Magento specific examples, the best are in the Magento core.

## Useful links

- [PHPUnit Manual (the holy grail!)](https://phpunit.de/manual/current/en/index.html)
- [Grump Learning - by Chris Hartjes](https://grumpy-learning.com/)
- [Introduction to unit testing - Sitepoint](http://www.sitepoint.com/tutorial-introduction-to-unit-testing-in-php-with-phpunit/)
- [Introduction to mock objects - Sitepoint](http://www.sitepoint.com/an-introduction-to-mock-object-testing/)
- [Hands on unit testing with PHPUnit - Tutsplus](http://code.tutsplus.com/tutorials/hands-on-unit-testing-with-phpunit--net-27454)

Got some useful resources yourself? Comment below, or add yourself (go to my github, link below)


Magento 2 module from scratch - Part 6: Unit Testing


> Magento 2 has been released! This entire series has been updated to reflect the changes since I originally wrote this post.
> I install Magento 2 using Composer, I recommend you do to! [Learn how to here](http://devdocs.magento.com/guides/v2.0/install-gde/install-quick-ref.html#installation-part-1-getting-started)

_This is part 5 of my ['Magento 2 Module From Scratch'](/magento2/module-from-scratch-introduction/) series. I'd recommend you catch up with the rest first._


Today I'm covering the admin area section of our module. In here, we add links to the main menu, create our grid using the UI Components in Magento 2, create mass actions, and the ability to edit each post!

I won't be going into a huge amount of depth, but you'll be able to follow along and understand how everything fits together. I attend on covering some of these areas later on as they can be entire blog posts in themselves!

First things first, we want to add our blog admin pages to the 'Content' menu. We can do this by creating the file: `etc/adminhtml/menu.xml`

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Backend:etc/menu.xsd">
    <menu>
        <add id="Ashsmith_Blog::blog_content" title="Blog" module="Ashsmith_Blog" sortOrder="50" parent="Magento_Backend::content" resource="Ashsmith_Blog::blog_content" />
        <add id="Ashsmith_Blog::post" title="Posts" module="Ashsmith_Blog" sortOrder="0" parent="Ashsmith_Blog::blog_content" action="blog/post" resource="Ashsmith_Blog::post"/>
    </menu>
</config>

```

So this is dead simple. within the `<menu>` node we instruct magento to add two new items. First, is simply a heading, the next is our main item which will link to the blog posts grid! I wanted to nest the blog under it's own section in case I decide to add Categories, tags or other common blog features in the future!

**Quick description of the parameters:**

- `id` - A unique id to give to the menu item. Namespace it with your module name to avoid conflicts.
- `title` - The text you want displayed!
- `module` - The module it belongs to
- `sortOrder` - Ordering within the list of items
- `parent` - The ability to specify what node this belongs to, or where to nest the menu item.
- `resource` - This relates to our ACL. We'll cover this next.
- `action` - If you want your link to be clickable specify the path: i.e. `blog/post` (`frontName/action`)

Great, we have our menu items. Next, let's define some ACL rules so that admins can give fine grain control over other admin users!

`etc/acl.xml`

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Magento_Backend::content">
                    <resource id="Ashsmith_Blog::blog_content" title="Blog" sortOrder="10" >
                        <resource id="Ashsmith_Blog::post" title="Blog Posts" sortOrder="40">
                            <resource id="Ashsmith_Blog::save" title="Save Blog Post" sortOrder="10" />
                            <resource id="Ashsmith_Blog::post_delete" title="Delete Blog Post" sortOrder="20" />
                        </resource>
                    </resource>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

```

The ACL may feel familiar to that of Magento 1.x. Because our blog belongs under the `Magento_Backend::content` in our menu, we need to embed our resources within there. Then using the same resource identifiers we used in our menu.xml we can define the access. That will handle displaying/hiding the links within the menu based on the users access rights. Finally, we have our save and delete resources. We'll be making use of these in our controllers and block to change how the page looks for certain users.

So we now have our menu, and ACL configured. Let's move onwards by defining our admin routes. As we have already specified a path for our menu link we'll need to use that same convention within our routes configuration. Start by creating: `etc/adminhtml/routes.xml`

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="admin">
        <route id="blog" frontName="blog">
            <module name="Ashsmith_Blog" before="Magento_Backend" />
        </route>
    </router>
</config>

```

This follows the same format as our frontend router, with the exception of the `router` node's `id` attribute being set to `admin`. We also specify that our module is put before the `Magento_Backend` module.

Now it's time to create our first controller. We'll start with making our grid!

All our admin controllers live within an `Controller/Adminhtml` directory. Let's create our first: `Controller/Adminhtml/Post/Index.php`

```php
<?php
namespace Ashsmith\Blog\Controller\Adminhtml\Post;

use Magento\Backend\App\Action\Context;
use Magento\Framework\View\Result\PageFactory;

class Index extends \Magento\Backend\App\Action
{

    /**
     * @var PageFactory
     */
    protected $resultPageFactory;

    /**
     * @param Context $context
     * @param PageFactory $resultPageFactory
     */
    public function __construct(
        Context $context,
        PageFactory $resultPageFactory
    ) {
        parent::__construct($context);
        $this->resultPageFactory = $resultPageFactory;
    }

    /**
     * Index action
     *
     * @return \Magento\Backend\Model\View\Result\Page
     */
    public function execute()
    {
        /** @var \Magento\Backend\Model\View\Result\Page $resultPage */
        $resultPage = $this->resultPageFactory->create();
        $resultPage->setActiveMenu('Ashsmith_Blog::post');
        $resultPage->addBreadcrumb(__('Blog Posts'), __('Blog Posts'));
        $resultPage->addBreadcrumb(__('Manage Blog Posts'), __('Manage Blog Posts'));
        $resultPage->getConfig()->getTitle()->prepend(__('Blog Posts'));

        return $resultPage;
    }

    /**
     * Is the user allowed to view the blog post grid.
     *
     * @return bool
     */
    protected function _isAllowed()
    {
        return $this->_authorization->isAllowed('Ashsmith_Blog::post');
    }


}

```

Much like a standard controller actions, but instead of extending `\Magento\Framework\App\Action\Action` we now extend `\Magento\Backend\App\Action`. On top of this we have set a constant named `ADMIN_RESOURCE` this is what we defined in our ACL for whether or not a user is allowed access to this page.

Now that we have our controller setup we need to setup the UI components that will make up our admin grid. If you want to learn more about UI Components, head to the Magento 2 dev docs: [http://devdocs.magento.com/guides/v2.0/ui-library/ui-library-component.html](http://devdocs.magento.com/guides/v2.0/ui-library/ui-library-component.html)

Before we dive in with our UI Components, we'll need to create our layout file: `view/adminhtml/layout/blog_post_index.xml`

In here we simply register our UI Component!

```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <update handle="styles"/>
    <body>
        <referenceContainer name="content">
            <uiComponent name="blog_post_listing"/>
        </referenceContainer>
    </body>
</page>

```

We've registered our component, so lets create it, again this is just another XML based configuration file. It's fairly beefy, as this controls adding all the components that make up our grid view. Such as columns and mass actions!

`views/adminhtml/ui_component/blog_post_listing.xml`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#blog_post_listing.xml`

Let's quickly cover what we've done here:

- Setup and configure our JS, and data sources
- Define our containers
- Define our filter components
- Define our mass actions components
- Define our paging components
- Define our columns for the grid component
    - Our last column is an 'actions' column, allowing you to edit or delete from a little dropdown menu.

In here we have used 3 custom classes.

Under our `<dataSource>` node we defined the class: `PostGridDataProvider`. However, this doesn't
exist. Don't worry though, this is where Dependency Injection comes in. We'll setup a virtual type, which is an alias to our resource collection. So let's create our DI configuration file: `etc/di.xml`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#di.xml`

In our `di.xml` we have made 3 declarations. The first is the `<preference>` node, this essentially when `Ashsmith\Blog\Api\Data\PostInterface` is a dependency, use `Ashsmith\Blog\Model\Post`. This is essentially how we can implement our own logic into core Magento.. just implementing the interfaces and then using our `di.xml` to switch out the class. Simple! After that we define two virtual types. These are just aliases to other classes, both UI Components on which we need to customise the arguments passed (we provide `PostGridDataProvider` with our resource collection for example)

The next missing class was define on our last column `is_active` we defined a custom class for outputting the options available! This is a new class: `Ashsmith\Blog\Model\Post\Source\IsActive`. Let's create this quickly:

`Model/Post/Source/IsActive.php`:

`gist:e92df7f790cf6ce84b20c8ee28f1f400#IsActive.php`

The last class we're missing is the one we defined for our 'actions' column. This is another source for available actions to do to a single blog post

`Ui/Component/Listing/Column/PostActions.php`:

`gist:e92df7f790cf6ce84b20c8ee28f1f400#PostActions.php`

Now we have all our files required to make the grid page work, you should now be able to clear cache and access the grid page! Huzzah!

Next up, let's create our mass actions. So, we have already defined those as: Deleting, Enabling and Disabling posts. Each have their own controller actions, so let's create them:

`Controller/Adminhtml/Post/MassDelete.php`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#MassDelete.php`


That's our delete action done. Next up, our enable mass action: `Controller/Adminhtml/Post/MassEnable.php`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#MassEnable.php`

And finally the mass delete: `Controller/Adminhtml/Post/MassDisable.php`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#MassDisable.php`

Now that we can delete, enable and disable posts with Mass Actions, it's probably about time we made the ability to edit and create new posts! For this we need 3 more controllers: new, edit, save, and delete!

Let's start with the New action: `Controller/Adminhtml/Post/NewAction.php`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#NewAction.php`

All we do here is simply forward the request onto the edit controller!

Let's create our edit action: `Controller/Adminhtml/Post/Edit.php`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#Controller-Edit.php`

Before rendering the page, we attempt to load a record, and also check if any form data was previously submitted. If it was, we'll set the data on our model, then finally the model is added to the registry.

Let's create the delete action next:

`gist:e92df7f790cf6ce84b20c8ee28f1f400#Delete.php`


Now that we have our controllers setup, let's create our layout file, and blocks that will make up the page and display a form for us!

`view/adminhtml/layout/blog_post_edit.xml`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#blog_post_edit.xml`

Now we need to create our corresponding blocks!

`Block/Adminhtml/Post/Edit.php`
`gist:e92df7f790cf6ce84b20c8ee28f1f400#Edit.php`

And the form block too: `Block/Adminhtml/Post/Edit/Form.php`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#Form.php`

And there we have it! We're just missing the ability to save our blog posts now! So let's setup our final controller:

`Controller/Adminhtml/Post/Save.php`

`gist:e92df7f790cf6ce84b20c8ee28f1f400#Save.php`

### And that's it!

Clear cache, and you'll now have a fully functional Magento 2 module!

The final addition to the series will be adding unit tests to everything we have created. Check back soon!


Magento 2 module from scratch - Part 5: Adminhtml


> Magento 2 has been released! This entire series has been updated to reflect the changes since I originally wrote this post.
> I install Magento 2 using Composer, I recommend you do to! [Learn how to here](http://devdocs.magento.com/guides/v2.0/install-gde/install-quick-ref.html#installation-part-1-getting-started)

So far in the series we have created our model, resource model and database schema. It's finally time
to create something which we can see! It's time to setup our controller, blocks, layout and templates!

Let's start with our controller! You may have already read my blog post on [creating a controller in Magento 2](/2014/12/simple-magento2-controller-module/), so please check that out, and that is where a lot more detail will be kept regarding controllers!

Before creating our controller, we need to create a new XML configuration file: `etc/frontend/routes.xml`

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="standard">
        <route id="blog" frontName="blog">
            <module name="Ashsmith_Blog" />
        </route>
    </router>
</config>
```

Take a look at the `<route>` node, note how the frontName is `blog`. If you remember from Magento 1.x the URL our controller is mapped to is: `<frontName>/<controller>/<action>`. Well Magento 2 has followed the same structure! However, with one slight change. `<frontName>/<namespace>/<action>`.

Now, instead of having a single controller class with contains all our actions, we use a directory namespace to group our actions. Each action is it's own class extending `\Magento\Framework\App\Action\Action` and simply implementing the method `execute()`.

So, let's go ahead and create our blog index, this is how we'll list our latest blog posts.

Create a file called: `Controller/Index/Index.php`. This will map to: `/blog/` `/blog/index` and `/blog/index/index`.

```php
<?php
namespace Ashsmith\Blog\Controller\Index;

use \Magento\Framework\App\Action\Action;

class Index extends Action
{
    /** @var  \Magento\Framework\View\Result\Page */
    protected $resultPageFactory;
    /**
     * @param \Magento\Framework\App\Action\Context $context
     */
    public function __construct(\Magento\Framework\App\Action\Context $context,
                                \Magento\Framework\View\Result\PageFactory $resultPageFactory)
    {
        $this->resultPageFactory = $resultPageFactory;
        parent::__construct($context);
    }

    /**
     * Blog Index, shows a list of recent blog posts.
     *
     * @return \Magento\Framework\View\Result\PageFactory
     */
    public function execute()
    {
        return $this->resultPageFactory->create();
    }
}

```

Our controller is super light. We just need return an instance of `\Magento\Framework\View\Result\PageFactory`. When we come to creating our controller that will handle
viewing a single blog post, we'll cover adding custom layout handles, and dispatching events.

So, that's all we need from our blog/index/index controller!

Let's move onto creating our Block: `Block/PostList.php` (note how it's called PostList, we can't use List, it's a reserved word in PHP).

```php
<?php
namespace Ashsmith\Blog\Block;

use Ashsmith\Blog\Api\Data\PostInterface;
use Ashsmith\Blog\Model\ResourceModel\Post\Collection as PostCollection;

class PostList extends \Magento\Framework\View\Element\Template implements
    \Magento\Framework\DataObject\IdentityInterface
{
    /**
     * @var \Ashsmith\Blog\Model\ResourceModel\Post\CollectionFactory
     */
    protected $_postCollectionFactory;

    /**
     * Construct
     *
     * @param \Magento\Framework\View\Element\Template\Context $context
     * @param \Ashsmith\Blog\Model\ResourceModel\Post\CollectionFactory $postCollectionFactory,
     * @param array $data
     */
    public function __construct(
        \Magento\Framework\View\Element\Template\Context $context,
        \Ashsmith\Blog\Model\ResourceModel\Post\CollectionFactory $postCollectionFactory,
        array $data = []
    ) {
        parent::__construct($context, $data);
        $this->_postCollectionFactory = $postCollectionFactory;
    }

    /**
     * @return \Ashsmith\Blog\Model\ResourceModel\Post\Collection
     */
    public function getPosts()
    {
        // Check if posts has already been defined
        // makes our block nice and re-usable! We could
        // pass the 'posts' data to this block, with a collection
        // that has been filtered differently!
        if (!$this->hasData('posts')) {
            $posts = $this->_postCollectionFactory
                ->create()
                ->addFilter('is_active', 1)
                ->addOrder(
                    PostInterface::CREATION_TIME,
                    PostCollection::SORT_ORDER_DESC
                );
            $this->setData('posts', $posts);
        }
        return $this->getData('posts');
    }

    /**
     * Return identifiers for produced content
     *
     * @return array
     */
    public function getIdentities()
    {
        return [\Ashsmith\Blog\Model\Post::CACHE_TAG . '_' . 'list'];
    }

}
```

So first thing, our block extends `\Magento\Framework\View\Element\Template` and implements the `\Magento\Framework\Object\IdentityInterface` interface. The `Template` class can be compared to `Mage_Core_Block_Template`. Next our `IdentityInterface` requires the `getIdentities` method to be implemented. This is an identifier for caching our blocks output!

Next up we have the `getPosts` method. In this, we use our factory class (Magento creates these automatically if you think you missed a step!), the factory class simply handles instantiating our
collection for us, along with it's dependencies. Calling the `create()` method will create an instance
of our collection, then I have just ordered our collection to get the newest posts.

Now that we have our block, let's create our layout file, and templates!

Create the file: `view/frontend/layout/blog_index_index.xml`

```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column"
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Ashsmith\Blog\Block\PostList" name="blog.list" template="Ashsmith_Blog::list.phtml" />
        </referenceContainer>
    </body>
</page>

```

We can create a layout file per handle, and in here we can specify which blocks we want, and which template we require to use!

> I'd want to keep this post down in length, so I'm skipping over a fair bit about layout and templating.
> I will aim to cover it in more depth in a later post!

Let's move onto our actual template:


Create the file `view/frontend/templates/list.phtml`:

```php
<?php /** @var $block \Ashsmith\Blog\Block\PostList */ ?>
<h1><?php echo __('Latest Blog Posts') ?></h1>
<ul class="blog-post-list">
<?php /** @var $post \Ashsmith\Blog\Model\Post */ ?>
<?php foreach ($block->getPosts() as $post): ?>
    <li class="blog-post-list-item">
        <h3 class="blog-post-item-title">
            <a href="<?php echo $post->getUrl() ?>"><?php echo $post->getTitle() ?></a>
        </h3>

        <div class="blog-post-item-content">
            <?php echo $post->getContent(); ?>
        </div>

        <div class="blog-post-item-meta">
            <strong><?php echo __('Created at:') ?></strong> <?php echo $post->getCreationTime() ?>
        </div>
    </li>
<?php endforeach; ?>
</ul>

```

Nothing out of the ordinary here. You're probably very familiar with this!

The main thing to note is that `$this` is not your block anymore, it's actually the template engine. You
have access to another variable though: `$block`. That is your block!

Now, as you don't actually have any blog posts yet. You will want to put some into the database manually or the time being!
```sql
INSERT INTO `ashsmith_blog_post`
    (`post_id`, `url_key`, `title`, `content`, `is_active`, `creation_time`, `update_time`)
    VALUES
    (NULL, 'test-1', 'test title 1', 'testing content 1', 1, '2015-08-17 22:59:00', '2015-07-17 22:59:00');
INSERT INTO `ashsmith_blog_post`
    (`post_id`, `url_key`, `title`, `content`, `is_active`, `creation_time`, `update_time`)
    VALUES
    (NULL, 'test-2', 'test title 2', 'testing content 2', 1, '2015-08-17 22:59:00', '2015-07-17 22:59:00');
```

Now, clear cache and head to `blog/`. You will see a list of blog posts!

Now that we have our list of blog posts, you'll notice the URL's are nice and friendly (mystore.dev/blog/test-1 for example). So how do tell Magento how to handle those? Well, we can register a custom router. To do this, we create our router: `Controller/Router.php`, then we'll need to edit `etc/frontend/di.xml` within out module to register our custom router.

Create: `Controller/Router.php`

```php
<?php
namespace Ashsmith\Blog\Controller;

class Router implements \Magento\Framework\App\RouterInterface
{
    /**
     * @var \Magento\Framework\App\ActionFactory
     */
    protected $actionFactory;

    /**
     * Post factory
     *
     * @var \Ashsmith\Blog\Model\PostFactory
     */
    protected $_postFactory;

    /**
     * @param \Magento\Framework\App\ActionFactory $actionFactory
     * @param \Ashsmith\Blog\Model\PostFactory $postFactory
     */
    public function __construct(
        \Magento\Framework\App\ActionFactory $actionFactory,
        \Ashsmith\Blog\Model\PostFactory $postFactory
    ) {
        $this->actionFactory = $actionFactory;
        $this->_postFactory = $postFactory;
    }

    /**
     * Validate and Match Blog Post and modify request
     *
     * @param \Magento\Framework\App\RequestInterface $request
     * @return bool
     */
    public function match(\Magento\Framework\App\RequestInterface $request)
    {
        $url_key = trim($request->getPathInfo(), '/blog/');
        $url_key = rtrim($url_key, '/');

        /** @var \Ashsmith\Blog\Model\Post $post */
        $post = $this->_postFactory->create();
        $post_id = $post->checkUrlKey($url_key);
        if (!$post_id) {
            return null;
        }

        $request->setModuleName('blog')
            ->setControllerName('view')
            ->setActionName('index')
            ->setParam('post_id', $post_id);
        $request->setAlias(\Magento\Framework\Url::REWRITE_REQUEST_PATH_ALIAS, $url_key);

        return $this->actionFactory->create('Magento\Framework\App\Action\Forward');
    }
}

```

We have to follow the `\Magento\Framework\App\RouterInterface` interface, which requires the `match` method, from here we can fetch the URL key of the post from the request path. We do this by stripping out the `/blog/` and any trailing slashes on the end of the request path. Then we can check if it exists, if it doesn't we return null. This will then skip our router and if there are any other routers to be checked it'll carry on until it hits the default 404 page. If there is a match we update the request with our controller/action along with the blog post id. Then we forward the request.

Right, to get this working we need to add our Router into the list of routers, this is done with `etc/frontend/di.xml`.

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Framework\App\RouterList">
        <arguments>
            <argument name="routerList" xsi:type="array">
                <item name="blog" xsi:type="array">
                    <item name="class" xsi:type="string">Ashsmith\Blog\Controller\Router</item>
                    <item name="disable" xsi:type="boolean">false</item>
                    <item name="sortOrder" xsi:type="string">70</item>
                </item>
            </argument>
        </arguments>
    </type>
</config>

```

Let's create our controller, block, layout and template for viewing a single blog post. We'll fly over this as we've covered a lot of this already.

File: `Controller/View/Index.php`

```php
<?php
namespace Ashsmith\Blog\Controller\View;

use \Magento\Framework\App\Action\Action;

class Index extends Action
{
    /** @var  \Magento\Framework\View\Result\Page */
    protected $resultPageFactory;

    /**
     * @param \Magento\Framework\App\Action\Context $context
     */
    public function __construct(\Magento\Framework\App\Action\Context $context,
                                \Magento\Framework\Controller\Result\ForwardFactory $resultForwardFactory
    )
    {
        $this->resultForwardFactory = $resultForwardFactory;
        parent::__construct($context);
    }

    /**
     * Blog Index, shows a list of recent blog posts.
     *
     * @return \Magento\Framework\View\Result\PageFactory
     */
    public function execute()
    {
        $post_id = $this->getRequest()->getParam('post_id', $this->getRequest()->getParam('id', false));
        /** @var \Ashsmith\Blog\Helper\Post $post_helper */
        $post_helper = $this->_objectManager->get('Ashsmith\Blog\Helper\Post');
        $result_page = $post_helper->prepareResultPost($this, $post_id);
        if (!$result_page) {
            $resultForward = $this->resultForwardFactory->create();
            return $resultForward->forward('noroute');
        }
        return $result_page;
    }
}

```

We've taken a slightly different approach to last time and instead of keeping a lot
of the logic within our controller we have moved it out to a helper method.

Create our helper: `Helper/Post.php`
```php
<?php namespace Ashsmith\Blog\Helper;

use Magento\Framework\App\Action\Action;

class Post extends \Magento\Framework\App\Helper\AbstractHelper
{

    /**
     * @var \Ashsmith\Blog\Model\Post
     */
    protected $_post;

    /**
     * @var \Magento\Framework\View\Result\PageFactory
     */
    protected $resultPageFactory;

    /**
     * Constructor
     *
     * @param \Magento\Framework\App\Helper\Context $context
     * @param \Ashsmith\Blog\Model\Post $post
     * @param \Magento\Framework\View\Result\PageFactory $resultPageFactory
     * @SuppressWarnings(PHPMD.ExcessiveParameterList)
     */
    public function __construct(
        \Magento\Framework\App\Helper\Context $context,
        \Ashsmith\Blog\Model\Post $post,
        \Magento\Framework\View\Result\PageFactory $resultPageFactory
    )
    {
        $this->_post = $post;
        $this->resultPageFactory = $resultPageFactory;
        parent::__construct($context);
    }

    /**
     * Return a blog post from given post id.
     *
     * @param Action $action
     * @param null $postId
     * @return \Magento\Framework\View\Result\Page|bool
     */
    public function prepareResultPost(Action $action, $postId = null)
    {
        if ($postId !== null && $postId !== $this->_post->getId()) {
            $delimiterPosition = strrpos($postId, '|');
            if ($delimiterPosition) {
                $postId = substr($postId, 0, $delimiterPosition);
            }

            if (!$this->_post->load($postId)) {
                return false;
            }
        }

        if (!$this->_post->getId()) {
            return false;
        }

        /** @var \Magento\Framework\View\Result\Page $resultPage */
        $resultPage = $this->resultPageFactory->create();
        // We can add our own custom page handles for layout easily.
        $resultPage->addHandle('blog_post_view');

        // This will generate a layout handle like: blog_post_view_id_1
        // giving us a unique handle to target specific blog posts if we wish to.
        $resultPage->addPageLayoutHandles(['id' => $this->_post->getId()]);

        // Magento is event driven after all, lets remember to dispatch our own, to help people
        // who might want to add additional functionality, or filter the posts somehow!
        $this->_eventManager->dispatch(
            'ashsmith_blog_post_render',
            ['post' => $this->_post, 'controller_action' => $action]
        );

        return $resultPage;
    }
}

```

Create our Block: `Block/PostView.php`
```php
<?php
namespace Ashsmith\Blog\Block;

class PostView extends \Magento\Framework\View\Element\Template implements
    \Magento\Framework\DataObject\IdentityInterface
{

    /**
     * Construct
     *
     * @param \Magento\Framework\View\Element\Template\Context $context
     * @param \Ashsmith\Blog\Model\Post $post
     * @param \Ashsmith\Blog\Model\PostFactory $postFactory
     * @param array $data
     */
    public function __construct(
        \Magento\Framework\View\Element\Template\Context $context,
        \Ashsmith\Blog\Model\Post $post,
        \Ashsmith\Blog\Model\PostFactory $postFactory,
        array $data = []
    )
    {
        parent::__construct($context, $data);
        $this->_post = $post;
        $this->_postFactory = $postFactory;
    }

    /**
     * @return \Ashsmith\Blog\Model\Post
     */
    public function getPost()
    {
        // Check if posts has already been defined
        // makes our block nice and re-usable! We could
        // pass the 'posts' data to this block, with a collection
        // that has been filtered differently!
        if (!$this->hasData('post')) {
            if ($this->getPostId()) {
                /** @var \Ashsmith\Blog\Model\Post $page */
                $post = $this->_postFactory->create();
            } else {
                $post = $this->_post;
            }
            $this->setData('post', $post);
        }
        return $this->getData('post');
    }

    /**
     * Return identifiers for produced content
     *
     * @return array
     */
    public function getIdentities()
    {
        return [\Ashsmith\Blog\Model\Post::CACHE_TAG . '_' . $this->getPost()->getId()];
    }

}

```

Create our layout file: `view/frontend/layout/blog_view_index.xml`
```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column"
    xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Ashsmith\Blog\Block\PostView" name="blog.list" template="Ashsmith_Blog::view.phtml" />
        </referenceContainer>
    </body>
</page>

```

And finally our template file: `view/frontend/templates/view.phtml`
```php
<?php
/** @var $block \Ashsmith\Blog\Block\PostView */
/** @var $post \Ashsmith\Blog\Model\Post */
$post = $block->getPost();
?>
<h1 class="blog-post-item-title"><?php echo $post->getTitle() ?></h1>

<div class="blog-post-item-content">
    <?php echo $post->getContent(); ?>
</div>

<div class="blog-post-item-meta">
    <strong><?php echo __('Created at:') ?></strong> <?php echo $post->getCreationTime() ?>
</div>

```

And that's it! Now, clear cache and vist `blog/` again, and click on a blog post title.
You should now see you're on something like: `blog/test-1`.


##### What's up next
In part 5 we'll be creating our [admin interface for creating, editing and deleting blog posts](/magento2/module-from-scratch-part-5-adminhtml)!


Magento 2 module from scratch - Part 4: Frontend


> Magento 2 has been released! This entire series has been updated to reflect the changes since I originally wrote this post.
> I install Magento 2 using Composer, I recommend you do to! [Learn how to here](http://devdocs.magento.com/guides/v2.0/install-gde/install-quick-ref.html#installation-part-1-getting-started)

In the last part of the series we cover creating our model & resource model so that we can interact
with the database. However, we haven't yet created our table! This part of the series will soon fix that!

I separated this into it's own post as I felt it needed it's own post!

If you haven't been following along on the series, I highly recommend you read [part one](/magento2/module-from-scratch-module-part-1), and part two, and checkout the module we'll be creating over on [GitHub](https://github.com/ashsmith/magento2-blog-module-tutorial).

In Magento 1.x you'll know that to make changes to the database we would create setup/upgrade scripts
to handle this. Well, that hasn't changed, it's just now we take an OOP approach.

Now, I'd like the mention something I noticed before we get started. As it stands with the beta version of
Magento 2, I don't personally understand how our setup classes link to speicifc versions of our modules.
You'll notice this too as we go forward, you may also ask yourself how you can control which order these can be run in. As it stands, I have no idea and hope to find out!

Let's dive in!

Remember in `etc/module.xml` we defined the `setup_version`? Well, this is what is used to tell Magento 2
which version our module is currently at, and will decide if upgrade or setup scripts need to be run.

When you first install your module and run `bin/magento setup:upgrade` our Setup script will be ran, and a record inserted into a table called `setup_module`, which is the same as the `core_resource` table from Magento 1.x.

So let's create our Setup class to install our database!

Create a file called: `Setup/InstallSchema.php`

```php
<?php namespace Ashsmith\Blog\Setup;

use Magento\Framework\Setup\InstallSchemaInterface;
use Magento\Framework\Setup\ModuleContextInterface;
use Magento\Framework\Setup\SchemaSetupInterface;
use Magento\Framework\DB\Ddl\Table;

class InstallSchema implements InstallSchemaInterface
{
    /**
     * Installs DB schema for a module
     *
     * @param SchemaSetupInterface $setup
     * @param ModuleContextInterface $context
     * @return void
     */
    public function install(SchemaSetupInterface $setup, ModuleContextInterface $context)
    {
        $installer = $setup;

        $installer->startSetup();

        $table = $installer->getConnection()
            ->newTable($installer->getTable('ashsmith_blog_post'))
            ->addColumn(
                'post_id',
                Table::TYPE_SMALLINT,
                null,
                ['identity' => true, 'nullable' => false, 'primary' => true],
                'Post ID'
            )
            ->addColumn('url_key', Table::TYPE_TEXT, 100, ['nullable' => true, 'default' => null])
            ->addColumn('title', Table::TYPE_TEXT, 255, ['nullable' => false], 'Blog Title')
            ->addColumn('content', Table::TYPE_TEXT, '2M', [], 'Blog Content')
            ->addColumn('is_active', Table::TYPE_SMALLINT, null, ['nullable' => false, 'default' => '1'], 'Is Post Active?')
            ->addColumn('creation_time', Table::TYPE_DATETIME, null, ['nullable' => false], 'Creation Time')
            ->addColumn('update_time', Table::TYPE_DATETIME, null, ['nullable' => false], 'Update Time')
            ->addIndex($installer->getIdxName('blog_post', ['url_key']), ['url_key'])
            ->setComment('Ash Smith Blog Posts');

        $installer->getConnection()->createTable($table);

        $installer->endSetup();
    }

}
```

The name of this class can be anything you want. You just need to implement the interface `Magento\Framework\Setup\InstallSchemaInterface`. What do you do if you want to create an upgrade
script? Well, you'd implement `Magento\Framework\Setup\UpgradeSchemaInterface`.

If you need to check the version of your module between upgrades, you will now need to manage that yourself. You can find out more from my [magento.stackexchange.com question on handling upgrade scripts in magento 2](http://magento.stackexchange.com/questions/79201/how-do-you-control-ordering-of-upgrade-setup-scripts-in-magento-2)

Now we can head to the CLI and run the `bin/magento` command to install our database table!

```bash
bin/magento setup:upgrade
```

When you run this you should see something along the lines of:

```bash
    $ bin/magento setup:db-schema:upgrade
    Schema creation/updates:
    Module 'Ashsmith_Blog':
    Installing schema..
    Module 'Magento_Store':
    ...
```

That shows it has picked up your Schema Setup and ran it successfully!

>*Note:* If you run into any issues, it will be because you have already installed the module from the first part of my series. You will need to go into the `setup_module` table and delete your module from the table. Then re-run the `bin/magento setup:upgrade` command.

[Part 4 covers: frontend controllers, blocks and templates](/magento2/module-from-scratch-part-4-the-frontend)

You can view the complete module over on GitHub. [Magento 2 Blog Module](https://github.com/ashsmith/magento2-blog-module-tutorial)


Magento 2 module from scratch - Part 3: Setup classes & databases


> Magento 2 has been released! This entire series has been updated to reflect the changes since I originally wrote this post.
> I install Magento 2 using Composer, I recommend you do to! [Learn how to here](http://devdocs.magento.com/guides/v2.0/install-gde/install-quick-ref.html#installation-part-1-getting-started)

If you haven't been following along on the series, I highly recommend you read [part one](/magento2/module-from-scratch-module-part-1-setup/), and checkout the module we'll be creating over on [GitHub](https://github.com/ashsmith/magento2-blog-module-tutorial).

Today's post is going to cover a fair bit, so grab yourself a cuppa. We'll be covering:

- Models
- Resource Models

At the end of this post you will have successfully created your first Service Contract, along with your Model, and Resource Model. A lot of this will feel familiar from Magento 1.x. So don't worry, it's not too different! You'll soon start to feel comfortable!

So let's dive in!

Magento 2 has a lot of new conventions, and a few of those I'll be covering today. The first of which
is it's use of PHP Interfaces. Our blog module will only require one database table, and that table will be named: `ashsmith_blog_post`, namespaced so we don't conflict with other tables, and descriptive of what it relates to. Our model will be called `Post`. So we'll need to create an interface for our `Post` model before we get started! Specifically the interface we're creating is referred to as a data interface.

If you want to learn more about how interfaces are used, devdocs.magento.com have some excellent posts covering this.

- [Service Contracts](http://devdocs.magento.com/guides/v2.0/extension-dev-guide/service-contracts/service-contracts.html)
- [Service Contracts - Data interfaces](http://devdocs.magento.com/guides/v2.0//extension-dev-guide/service-contracts/design-patterns.html#data-interfaces)

Before we build our interface, let's decide on how the blog post table will look. It will have the following columns:

- post_id - our post unique identifier
- url_key - a unique url key, for pretty URLs
- title - the title of our post
- content - the blog post content
- creation_time - timestamp
- update_time - timestamp
- is_active - boolean value if the post is active or not.

Ok, knowing this we can now create our interface. In our project we want to create a new file called: `Api/Data/PostInterface.php`, and inside it we want the following:

```php
<?php
namespace Ashsmith\Blog\Api\Data;


interface PostInterface
{
    /**
     * Constants for keys of data array. Identical to the name of the getter in snake case
     */
    const POST_ID       = 'post_id';
    const URL_KEY       = 'url_key';
    const TITLE         = 'title';
    const CONTENT       = 'content';
    const CREATION_TIME = 'creation_time';
    const UPDATE_TIME   = 'update_time';
    const IS_ACTIVE     = 'is_active';

    /**
     * Get ID
     *
     * @return int|null
     */
    public function getId();

    /**
     * Get URL Key
     *
     * @return string
     */
    public function getUrlKey();

    /**
     * Get title
     *
     * @return string|null
     */
    public function getTitle();

    /**
     * Get content
     *
     * @return string|null
     */
    public function getContent();

    /**
     * Get creation time
     *
     * @return string|null
     */
    public function getCreationTime();

    /**
     * Get update time
     *
     * @return string|null
     */
    public function getUpdateTime();

    /**
     * Is active
     *
     * @return bool|null
     */
    public function isActive();

    /**
     * Set ID
     *
     * @param int $id
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setId($id);

    /**
     * Set URL Key
     *
     * @param string $url_key
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setUrlKey($url_key);

    /**
     * Set title
     *
     * @param string $title
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setTitle($title);

    /**
     * Set content
     *
     * @param string $content
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setContent($content);

    /**
     * Set creation time
     *
     * @param string $creationTime
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setCreationTime($creationTime);

    /**
     * Set update time
     *
     * @param string $updateTime
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setUpdateTime($updateTime);

    /**
     * Set is active
     *
     * @param int|bool $isActive
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setIsActive($isActive);
}
```

This interface has defined all the setters and getters we would use when interacting with our model.
It also outlines all the methods we must implement! So, let's create our Model!

This file goes to: `Model/Post.php`

```php
<?php namespace Ashsmith\Blog\Model;

use Ashsmith\Blog\Api\Data\PostInterface;
use Magento\Framework\DataObject\IdentityInterface;

class Post  extends \Magento\Framework\Model\AbstractModel implements PostInterface, IdentityInterface
{

    /**#@+
     * Post's Statuses
     */
    const STATUS_ENABLED = 1;
    const STATUS_DISABLED = 0;
    /**#@-*/

    /**
     * CMS page cache tag
     */
    const CACHE_TAG = 'blog_post';

    /**
     * @var string
     */
    protected $_cacheTag = 'blog_post';

    /**
     * Prefix of model events names
     *
     * @var string
     */
    protected $_eventPrefix = 'blog_post';

    /**
     * Initialize resource model
     *
     * @return void
     */
    protected function _construct()
    {
        $this->_init('Ashsmith\Blog\Model\ResourceModel\Post');
    }

    /**
     * Check if post url key exists
     * return post id if post exists
     *
     * @param string $url_key
     * @return int
     */
    public function checkUrlKey($url_key)
    {
        return $this->_getResource()->checkUrlKey($url_key);
    }

    /**
     * Prepare post's statuses.
     * Available event blog_post_get_available_statuses to customize statuses.
     *
     * @return array
     */
    public function getAvailableStatuses()
    {
        return [self::STATUS_ENABLED => __('Enabled'), self::STATUS_DISABLED => __('Disabled')];
    }
    /**
     * Return unique ID(s) for each object in system
     *
     * @return array
     */
    public function getIdentities()
    {
        return [self::CACHE_TAG . '_' . $this->getId()];
    }

    /**
     * Get ID
     *
     * @return int|null
     */
    public function getId()
    {
        return $this->getData(self::POST_ID);
    }

    /**
     * Get URL Key
     *
     * @return string
     */
    public function getUrlKey()
    {
        return $this->getData(self::URL_KEY);
    }

    /**
     * Get title
     *
     * @return string|null
     */
    public function getTitle()
    {
        return $this->getData(self::TITLE);
    }

    /**
     * Get content
     *
     * @return string|null
     */
    public function getContent()
    {
        return $this->getData(self::CONTENT);
    }

    /**
     * Get creation time
     *
     * @return string|null
     */
    public function getCreationTime()
    {
        return $this->getData(self::CREATION_TIME);
    }

    /**
     * Get update time
     *
     * @return string|null
     */
    public function getUpdateTime()
    {
        return $this->getData(self::UPDATE_TIME);
    }

    /**
     * Is active
     *
     * @return bool|null
     */
    public function isActive()
    {
        return (bool) $this->getData(self::IS_ACTIVE);
    }

    /**
     * Set ID
     *
     * @param int $id
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setId($id)
    {
        return $this->setData(self::POST_ID, $id);
    }

    /**
     * Set URL Key
     *
     * @param string $url_key
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setUrlKey($url_key)
    {
        return $this->setData(self::URL_KEY, $url_key);
    }

    /**
     * Set title
     *
     * @param string $title
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setTitle($title)
    {
        return $this->setData(self::TITLE, $title);
    }

    /**
     * Set content
     *
     * @param string $content
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setContent($content)
    {
        return $this->setData(self::CONTENT, $content);
    }

    /**
     * Set creation time
     *
     * @param string $creation_time
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setCreationTime($creation_time)
    {
        return $this->setData(self::CREATION_TIME, $creation_time);
    }

    /**
     * Set update time
     *
     * @param string $update_time
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setUpdateTime($update_time)
    {
        return $this->setData(self::UPDATE_TIME, $update_time);
    }

    /**
     * Set is active
     *
     * @param int|bool $is_active
     * @return \Ashsmith\Blog\Api\Data\PostInterface
     */
    public function setIsActive($is_active)
    {
        return $this->setData(self::IS_ACTIVE, $is_active);
    }

}
```

As you can see we have implemented each method from our `PostInterface` interface. You will also notice
we have implemented a second interface too, `Magento\Framework\DataObject\IdentityInterface`. This interface
is used for models which require cache refresh after creation/updating/deletion, and models that render
information to the frontend. This simply requires us to implement the `getIdentities()` method. Which will return a unique ID for each instance of our model, that is cacheable.

On top of the methods implemented by our interfaces we have also implemented:

- _construct - This allows us to initialise our resource model, like in Magento 1.x
- getAvailableStatuses - Along with the two constants, we can use this to restrict what statuses can be used.
- checkUrlKey - This will allow us to check if a post with that URL Key already exists!

Furthermore, you'll notice some attributes defined at the top of our class:

- $_cacheTag - a unique identifier for use within caching
- $_eventPrefix - a prefix for events to be triggered. We'll cover this more later.

Now it's time to create our resource model! This goes in: `Model/ResourceModel/Post.php`

```php
<?php
namespace Ashsmith\Blog\Model\ResourceModel;

/**
 * Blog post mysql resource
 */
class Post extends \Magento\Framework\Model\ResourceModel\Db\AbstractDb
{

    /**
     * @var \Magento\Framework\Stdlib\DateTime\DateTime
     */
    protected $_date;

    /**
     * Construct
     *
     * @param \Magento\Framework\Model\ResourceModel\Db\Context $context
     * @param \Magento\Framework\Stdlib\DateTime\DateTime $date
     * @param string|null $resourcePrefix
     */
    public function __construct(
        \Magento\Framework\Model\ResourceModel\Db\Context $context,
        \Magento\Framework\Stdlib\DateTime\DateTime $date,
        $resourcePrefix = null
    ) {
        parent::__construct($context, $resourcePrefix);
        $this->_date = $date;
    }

    /**
     * Initialize resource model
     *
     * @return void
     */
    protected function _construct()
    {
        $this->_init('ashsmith_blog_post', 'post_id');
    }

    /**
     * Process post data before saving
     *
     * @param \Magento\Framework\Model\AbstractModel $object
     * @return $this
     * @throws \Magento\Framework\Exception\LocalizedException
     */
    protected function _beforeSave(\Magento\Framework\Model\AbstractModel $object)
    {

        if (!$this->isValidPostUrlKey($object)) {
            throw new \Magento\Framework\Exception\LocalizedException(
                __('The post URL key contains capital letters or disallowed symbols.')
            );
        }

        if ($this->isNumericPostUrlKey($object)) {
            throw new \Magento\Framework\Exception\LocalizedException(
                __('The post URL key cannot be made of only numbers.')
            );
        }

        if ($object->isObjectNew() && !$object->hasCreationTime()) {
            $object->setCreationTime($this->_date->gmtDate());
        }

        $object->setUpdateTime($this->_date->gmtDate());

        return parent::_beforeSave($object);
    }

    /**
     * Load an object using 'url_key' field if there's no field specified and value is not numeric
     *
     * @param \Magento\Framework\Model\AbstractModel $object
     * @param mixed $value
     * @param string $field
     * @return $this
     */
    public function load(\Magento\Framework\Model\AbstractModel $object, $value, $field = null)
    {
        if (!is_numeric($value) && is_null($field)) {
            $field = 'url_key';
        }

        return parent::load($object, $value, $field);
    }

    /**
     * Retrieve select object for load object data
     *
     * @param string $field
     * @param mixed $value
     * @param \Ashsmith\Blog\Model\Post $object
     * @return \Zend_Db_Select
     */
    protected function _getLoadSelect($field, $value, $object)
    {
        $select = parent::_getLoadSelect($field, $value, $object);

        if ($object->getStoreId()) {

            $select->where(
                'is_active = ?',
                1
            )->limit(
                1
            );
        }

        return $select;
    }

    /**
     * Retrieve load select with filter by url_key and activity
     *
     * @param string $url_key
     * @param int $isActive
     * @return \Magento\Framework\DB\Select
     */
    protected function _getLoadByUrlKeySelect($url_key, $isActive = null)
    {
        $select = $this->getConnection()->select()->from(
            ['bp' => $this->getMainTable()]
        )->where(
            'bp.url_key = ?',
            $url_key
        );

        if (!is_null($isActive)) {
            $select->where('bp.is_active = ?', $isActive);
        }

        return $select;
    }

    /**
     *  Check whether post url key is numeric
     *
     * @param \Magento\Framework\Model\AbstractModel $object
     * @return bool
     */
    protected function isNumericPostUrlKey(\Magento\Framework\Model\AbstractModel $object)
    {
        return preg_match('/^[0-9]+$/', $object->getData('url_key'));
    }

    /**
     *  Check whether post url key is valid
     *
     * @param \Magento\Framework\Model\AbstractModel $object
     * @return bool
     */
    protected function isValidPostUrlKey(\Magento\Framework\Model\AbstractModel $object)
    {
        return preg_match('/^[a-z0-9][a-z0-9_\/-]+(\.[a-z0-9_-]+)?$/', $object->getData('url_key'));
    }

    /**
     * Check if post url key exists
     * return post id if post exists
     *
     * @param string $url_key
     * @return int
     */
    public function checkUrlKey($url_key)
    {
        $select = $this->_getLoadByUrlKeySelect($url_key, 1);
        $select->reset(\Zend_Db_Select::COLUMNS)->columns('bp.post_id')->limit(1);

        return $this->getConnection()->fetchOne($select);
    }
}
```

In here we have implemented the following methods:

- __construct - Where we inject dependencies we use in our resource model.
- _construct - Where we initialise our resource model, like we would in Magento 1.x this is where the database table and ID column is defined.
- _beforeSave, we need to make sure we're saving valid data, so a little validation is handled Here
- load, if the user provides a string instead of an id we try to load the model against the url_key column as that is still a uniquely identifiable column.
- _getLoadSelect allows us to filter to only active posts. We don't want to load inactive posts!
- _getLoadByUrlKeySelect allows us to select items by a url key.
- isNumericPostUrlKey is a validation method to see if our url key contains numbers. We don't want numeric url keys!
- isValidPostUrlKey, make sure the post url key is actually valid with a simple regex check.
- checkUrlKey, check if a URL Key exists in the posts table already.

Finally, we need a Collection resource model. The collection model will allow us to filter and fetch a collection of blog posts.

Create a file named: `Model/ResourceModel/Post/Collection.php`

```php
<?php namespace Ashsmith\Blog\Model\ResourceModel\Post;

class Collection extends \Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection
{
    /**
     * @var string
     */
    protected $_idFieldName = 'post_id';

    /**
     * Define resource model
     *
     * @return void
     */
    protected function _construct()
    {
        $this->_init('Ashsmith\Blog\Model\Post', 'Ashsmith\Blog\Model\ResourceModel\Post');
    }

}
```

As per Magento 1.x, this is going to look familiar. Nothing new here really. We initialise our Collection with both our model, and resource model.

So, how do we use our resource model in Magento 2? Well, a factory object is generated that handles instantiating our collection. We can inject this factory into our blocks (or wherever we want to use our collection!) and then we can do as we please! I'll cover this in the  post where we [create our controllers, blocks and templates](/magento2/module-from-scratch-part-4-the-frontend).

And that's how you create and models & resource models for interacting with a database. Did you notice we didn't have to write a single line of XML? Huzzah! Yup, Magento 2 has done away with having to register your models and resource models.

Ok! We have covered a lot, in the next post I'll be covering [how to create our table through Setup scripts](/magento2/module-from-scratch-part-3-database-tables). I'll also be touching on Upgrade scripts too. Until then, let me know in the comments what you think, or any questions.

You can view the complete module over on GitHub. [Magento 2 Blog Module](https://github.com/ashsmith/magento2-blog-module-tutorial)


Magento 2 module from scratch - Part 2: Models & Resource Models


Magento 2 is quickly becoming something us Magento developers need to learn pretty rapidly as we'll soon be expected to start building our clients stores on the platform and building extensions. I wanted to take the opportunity to create a simple set of posts which will go over, at a bit of a high level, on how to create a full blown magento 2 module.. with admin management, and unit tests!

So, by the end of this small series of blog posts you will be able to do the following, with ease:

- Creating a module that is installable via Composer
- Create controllers and understand how the rewrite system works
- How blocks, layouts and template work
- Create models and interact with the database
- Setup an admin interface to create, edit and delete items from the database.
- Create unit tests to support all of the above!

## What are we going to build?
The end extension will be a fairly basic blog, you'll be able create blog posts from the admin including editing and deleting them. Then from the frontend you will be able to view a list of all the blog posts, and view each blog post individually. I believe this will allow us to cover all the essentials into building a magento extension!

1. [Basic Module Setup](/magento2/module-from-scratch-module-part-1-setup/)
2. [Setting up our Models & Resource Models](/magento2/module-from-scratch-module-part-2-models/)
3. [Migrations & Database Schema!](/magento2/module-from-scratch-part-3-database-tables)
4. [The Frontend: Controllers, Blocks, layouts & views](/magento2/module-from-scratch-part-4-the-frontend)
5. [The Backend: Controllers, Blocks, UI, layouts and views](/magento2/module-from-scratch-part-5-adminhtml/)
6. [Unit testing](/magento2/module-from-scratch-part-6-unit-testing)


Magento 2 module from scratch - Introduction


> Magento 2 has been released! This entire series has been updated to reflect the changes since I originally wrote this post.
> I install Magento 2 using Composer, I recommend you do to! [Learn how to here](http://devdocs.magento.com/guides/v2.0/install-gde/install-quick-ref.html#installation-part-1-getting-started)

If you're here, then you are going to be just excited as I am about creating a full blown
Magento 2 module from scratch! This part of the series I'll be covering how to setup your
module so that it can be installed via Composer.

To install a module via Composer we'll need to set it up as a public version controlled repository and
submit it to packagist.org. I'll walk you through how your composer.json should look, anything else is
best left to [the composer documentation](https://getcomposer.org/).

I'll be assuming you have already setup a basic repository, and you are familiar with the CLI.

## Module structure
Let's setup our basic module structure now:

```bash
    etc/module.xml
    registration.php
```

In the root directory we'll want to create a composer.json file. And it should look something like this:
```json
    {
        "name": "ashsmith/magento2-blog",
        "description": "A simple blog module.",
        "type": "magento2-module",
        "version": "1.0.0",
        "license": [
            "OSL-3.0",
            "AFL-3.0"
        ],
        "require": {
            "php": "~5.5.0|~5.6.0",
            "magento/magento-composer-installer": "*"
        },
        "extra": {
            "map": [
                [
                    "*",
                    "Ashsmith/Blog"
                ]
            ]
        }
    }
```

There are only a few elements to this I want to explain, as some of it may be unfamiliar to you.
```json
    "type": "magento2-module"
```

This defines our repo as a magento2-module, this is so when someone includes your module as a
dependency on their Magento 2 install, composer will know what to do with it! And that brings us to the next bit
```json

    "extra": {
        "map": [
            [
                "*",
                "Ashsmith/Blog"
            ]
        ]
    }
```

What this does is creates a map which will tell Composer how to install this module.

That is: everything (*) should go into the folder: `Ashsmith/Blog`. Which would mean our module will be installed to: `app/code/Ashsmith/Blog`.

> If you want to learn more about this, head to Alan Kent's blog! [This is a fantastic post covering Magento 2 & composer](http://alankent.me/2014/08/03/creating-a-magento-2-composer-module/)


The first file you'll want to create is the `etc/module.xml`.
```xml
    <?xml version="1.0"?>
    <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
        <module name="Ashsmith_Blog" setup_version="1.0.0" />
    </config>
```

> Noticed the Schema location is a little strange looking? Your IDE won't recongise that, but you can fix that! Here how in PHPStorm: [XML Schema Resolution in PHPStorm](http://alankent.me/2015/10/07/xml-schema-resolution-in-php-storm-with-urns-quick-note/)

Next up, we need a `registration.php` file in the root of our module. This is picked up by the Magento framework and will handle registering your module with Magento.

```php
<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'Ashsmith_Blog',
    __DIR__
);
```

Now, with this done our module has is setup, but it won't work within Magento just yet. We will need to enable it, then upgrade the database too. Like so:

```bash
    bin/magento module:status # this will give us the status of each module. It'll show ours as disabled.
    bin/magento module:enable Ashsmith_Blog # this will enable our module
    bin/magento setup:upgrade # upgrade the system, essentially this will make sure any setup scripts have been run and the current module version saved to the setup_module table.
    bin/magento module:status # confirm our module has been enabled!
```


If you want to skip over the Composer installation of the module, you can just create the `app/code` directory if it doesn't yet exist, and then copy in your code to the following structure: `app/code/Ashsmith/Blog/`.

## Conclusion

We've now set up our module, along with composer! If you push to a public repo, register it with packagist you will be able to install it really easily!

Next up, I'll cover how to [create your models & resource models in Magento 2](/magento2/module-from-scratch-module-part-2-models/).

You can view the complete module over on GitHub. [Magento 2 Blog Module](https://github.com/ashsmith/magento2-blog-module-tutorial)


Magento 2 module from scratch - Part 1: Module Setup


With the developer beta release of Magento 2 coming out just the other day, I decided it was a good time to take a look at how to create a simple module. The goal of this post is to help both you and myself to understand some of the new concepts/structures in Magento 2.

This post assumes you have good knowledge of Magento 1.x. You should be comfortable creating a module with controllers and blocks already.

## Basic module with controller, block and view.

Let's start with registering a module, and seeing how it works. I'm not going to do anything fancy, we're just going to output "Hello World" to the content block using a custom frontend route.

### Code Structure

The first thing you will notice in Magento 2 is there are no longer any code pools (local, community, and core). You only have `app/code/`. Naming conventions generally remain the same however. So, to start with our module we'll create the following directory: `app/code/Ashsmith/HelloWorld`.

You will also need the following sub-directories:

- `app/code/Ashsmith/HelloWorld/`
- `app/code/Ashsmith/HelloWorld/Block/`
- `app/code/Ashsmith/HelloWorld/Controller/Index/`
- `app/code/Ashsmith/HelloWorld/etc/frontend`
- `app/code/Ashsmith/HelloWorld/view/frontend/layout`
- `app/code/Ashsmith/HelloWorld/view/frontend/templates`

#### Brief overview of a modules structure

##### Block/
Blocks, as in Magento 1.x remain the same. Main difference being the class you extend is no longer `Mage_Core_Block_Template` but instead `\Magento\Framework\View\Element\Template`. Two differences here, the first is that Magento 2 now uses php namespacing instead of class names based on a modules structure with underscores. Second is that the core Magento framework has been moved into lib/Magento/Framework. We won't dive into this though.

##### Controller/
This folder replaces the `controller/` folder. Controllers have changed a fair bit, and we'll cover this in more depth later.

##### etc/
The `etc/` folder is still the place for module specific configuration, however now configuration for frontend and adminhtml is separated. For example in the module we make below we create two files: `etc/module.xml` and `etc/frontend/routes.xml`, and you would also have a `etc/adminhtml/routes.xml` if you wanted to register routes for the admin too.

The module.xml file is for registering the module, and telling Magento what dependencies the module has. This is a replacement for the app/etc/modules/Namespace_Module.xml file.

The frontend/routes.xml is where we register our controller and register it with the router for the frontend of the store.

There are more configuration files, and I'd advise you to take a look through some of the core Magento code in app/code/Magento to get a better idea (Customer module is my go-to module for seeing how everything works). I'll try and cover the other configuration files in a later post.

##### view/
The `view/` folder is entirely new. This is where your layout files and templates are now stored. This is the equivalent to storing them in `base/default` theme. By storing them here it means anything related to that module is kept in one place, installing and uninstalling a module is made easier (when there are no theme specific overrides).

All the changes like this, and the app/etc/modules/Namespace_Module.xml file being housed all under your modules folder is what I really love about Magento 2. No longer are your files scattered across the entire codebase. Installing and uninstalling modules will be easier.

#### Ok, let's make this module then!

I've rambled on long enough about the module structure, let's actually make something!

We'll start with our configuration files.

`app/code/Ashsmith/HelloWorld/etc/module.xml`


```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../lib/internal/Magento/Framework/Module/etc/module.xsd"> 
    <module name="Ashsmith_HelloWorld" schema_version="0.0.1" setup_version="0.0.1" /> 
</config>

``` 
This registers our module, we have no dependencies so we haven't listed any... however if your module does have a dependency then we simply change the `<module>` part of our module.xml file to look like this:


```xml
..
<module name="Ashsmith_HelloWorld" schema_version="0.0.1" setup_version="0.0.1"> 
    <sequence> 
        <module name="Magento_Eav"/> 
        <module name="Magento_Directory"/> 
    </sequence> 
</module>
..
```

Dead easy, right?

Next up, is our frontend router configuration file. Save this to `app/code/Ashsmith/HelloWorld/etc/frontend/routes.xml`


```xml
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../../lib/internal/Magento/Framework/App/etc/routes.xsd"> 
    <router id="standard"> 
        <route id="helloworld" frontName="helloworld"> 
            <module name="Ashsmith_HelloWorld" /> 
        </route> 
    </router> 
</config> 
```

Ok, so what have done here? To register a router we need to add to this: `<router id="standard">`, and if we wanted an admin router we do this: `<router id="admin">`. Simple. Next we define our route. The id attribute is simply an identifier, it should be unique. The frontName attribute is going to be the first part of the URL, in the completes example our URL is /helloworld/index/index/. This maps to Controller/Index/Index.php. The URL structure is as follows: /moduleFrontName/controller/action/param1/param2/param3.

With our route registered, now we can create our Controller action. This is something else that has changed in Magento 2 in comparison to 1.x in a fairly major way. Now, instead of specifying a controller class, which has multiple `[actionName]Action()` methods, you now have a class for each action, which implements a `execute` method. Here is the code:

File name: `app/code/Ashsmith/HelloWorld/Controller/Index/Index.php`


```php
<?php
namespace Ashsmith\HelloWorld\Controller\Index;

class Index extends \Magento\Framework\App\Action\Action
{
        /**
         * @var \Magento\Framework\View\Result\PageFactory
         */
        protected $resultPageFactory;

        /**
         * @param \Magento\Framework\App\Action\Context $context
         * @param \Magento\Framework\View\Result\PageFactory resultPageFactory
         */
        public function __construct(
            \Magento\Framework\App\Action\Context $context,
            \Magento\Framework\View\Result\PageFactory $resultPageFactory
        )
        {
            $this->resultPageFactory = $resultPageFactory;
            parent::__construct($context);
        }
    /**
     * Default customer account page
     *
     * @return void
     */
    public function execute()
    {
        return $this->resultPageFactory->create();
    }
}
```

And there it is. That's how we implement a controller action. Let's quickly talk about what is going on inside the execute method.

Let's start with the `__construct` method we've implemented. The two parameters we expect both dependencies of our controller action. If you need to use the `__construct`, you only need to include `$context` and ensure the parent method is still executed.

So what is `$context`? Context gives you access to things like: the object manager, the URL model, and more. All very handy stuff! The Context class will handle the DI of those components for you.

Now what on earth is `$resultPageFactory`?! It's a factory object to handle the creation of our result page of course ;). That doesn't really help us much though. This object is all we need to call to render our page.. remember how Magento 1.x you had to do `$this->loadLayout()` and `$this->renderLayout`. Well, now you just need to do: `$this->resultPageFactory->create()`. Awesome!

##### Side note on routing...
It's important to note that the namespacing is important here. The full class **has** to be `Ashsmith\HelloWorld\Controller\Index\Index`. This is due to way routing is handled. Here's a section from the class `Magento\Framework\App\Router\ActionList`

```php
<?php
/**
 *
 * @copyright Copyright (c) 2014 X.commerce, Inc. (http://www.magentocommerce.com)
 */
namespace Magento\Framework\App\Router;

class ActionList
{
    ...

    public function get($module, $area, $namespace, $action)
    {
        if ($area) {
            $area = '\\' . $area;
        }
        if (in_array(strtolower($action), $this->reservedWords)) {
            $action .= 'action';
        }
        $fullPath = str_replace(
            '_',
            '\\',
            strtolower(
                $module . '\\controller' . $area . '\\' . $namespace . '\\' . $action
            )
        );
        if (isset($this->actions[$fullPath])) {
            return is_subclass_of($this->actions[$fullPath], $this->actionInterface) ? $this->actions[$fullPath] : null;
        }

        return null;
    }

    ...
}
```

What this method returns in the namespaced class it is expecting, and we can see from the parameters it passes a namespace, which when we step through the code using xDebug (requesting the page `/helloworld/index/` we see this `$namespace` is `index`. `$module` is `Ashsmith_HelloWorld`, `$area` = `null`, and `$action` = `index`.

I want to cover Magento 2 routing in more depth at a later stage. So we'll leave this here for now.

--

##### Creating our block

We have created our controller. Let's create a block next, our file will be: `app/code/Ashsmith/HelloWorld/Block/HelloWorld.php`. Now, in this example we're not going implement any methods, so it's a pointless class really, but if we were to implement some methods, in our template we would have access to them via the `$block` variable, NOT the `$this`. `$this` now refers to the template engine, you can get to your block from it, but `$block` makes this much easier and cleaner.

```php
<?php
namespace Ashsmith\HelloWorld\Block;
class HelloWorld extends \Magento\Framework\View\Element\Template
{
}
```

This extends the base template view class, this is the equivalent to `Mage_Core_Block_Template` in 1.x Magento.

##### Layout files & Templates!

Now let's create our layout configuration file and the template. We'll start with layout

File name: `app/code/Ashsmith/HelloWorld/view/frontend/layout/helloworld_index_index.xml`. Notice the naming convention, its our full route, this is important. On top of this we can create a `default.xml` which would be applied on every route. The customer module has a good example of this in: `app/code/Magento/Customer/view/frontend/layout`


```xml
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../../../lib/internal/Magento/Framework/View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Ashsmith\HelloWorld\Block\HelloWorld" name="helloworld" template="helloworld.phtml" />
        </referenceContainer>
    </body>
</page>
```

You'll recognise the language used, which means so you should be able to pick up how it works relatively quickly. `<body>` refers to everything within the `<body>` tag in the rendered HTML page. There is also a `<head>` where you can add blocks to the page such as adding CSS.

What we have done here is added our block to the `content` container, and set the template of our block to helloworld.phtml. So lets create that file now: `app/code/Ashsmith/HelloWorld/view/frontend/templates/helloworld.phtml`.

In this file we can just put some simple text in there for now:

```html
    <h1>Hello World!</h1> 

```

And that's it! Our Module is now complete!

Well, not quite. It doesn't actually work! Why? Well, we need to activate manually. At the time of writing the devdocs lacked this information. It is rather simple thought. You just need to add the module to `app/etc/config.php`. In this file is an array of configuration key/value pairs. Find the `modules` key, and add our module name `Ashsmith_HelloWorld` to the end of the array.

```php
<?php
return array(
    ..
    'modules' => array(
        ...
        'Magento_CurrencySymbol' => 1,
        'Magento_Wishlist' => 1,
        'Ashsmith_HelloWorld' => 1 # Here is our module!
    )
    ...
    );
```

Some quick notes:

- Magento 2 has a full page cache. So, if you're making changes and not seeing them run: `$ rm -rf var/page_cache/*`
- Don't forget to also clear the usual cache too.
- Oh and Magento 2 has a `var/generation` folder, where there is a lot of compiled code. If you're having issues, try emptying that too.

And a one liner for all your cache clearing needs:

        $ bin/magento cache:flush --all

## And that's a wrap!

By now you should have a fully functional hello world module. Awesome stuff.

## Update 29th Dec 2014

As requested in the comments, I have added the completed module to my github: [https://github.com/ashsmith/magento2-controller-module](https://github.com/ashsmith/magento2-controller-module)

## Update 15th Aug 2015

I've neglected updating this post. I've correct a few things with our controller and blocks. :)

The example on GitHub is now composer installable too! Check out the repo linked above to find out more!


Ash Smith

Cloud & Serverless Developer

Magento 2 Posts