Skip to content

Modes

  • Production
  • Developer
  • Default

Folders

  • Configuration: app/etc/
  • Framework: lib/internal/Magento/Framework
  • Modules: app/code/Magento
  • CLI tool: bin/magento
  • Themes: app/design/
  • Dev tools: dev/

PHP Class Types

  • Model/Resource Model/Collection: A way to interact with databases, other models etc
  • API Interfaces: An internal API defining the available operations
  • Controllers: Handling requests
  • Blocks: View Models for the templates
  • Observers: for hooking into events
  • Plugins: For wrapping around any other class' methods
  • Helpers: Uncategorised methods
  • Setup/Upgrade scripts: Database migrations
  • UI Components

Custom code types

Module

A way to group together a batch of related functionality

File path: app/code/ or vendor/

Classes are namespaced by their vendor name, then module name

etc/module.xml registration.php

etc/module.xml

Stores the module's name, version and dependencies

1
2
3
4
5
`/config/module/`
                 `@name="Module_Name"
                 `@schema_version="1.0.0"
                 `sequence/`
                           `module/@name="Dependency_Name"`

registration.php

1
   `Magento\Framework\Component\ComponentRegistrar::register(Magento\Framework\Component\ComponentRegistrar::MODULE, 'module_name', __DIR__);`

File System

  • app/: Custom code, themes, global configration
    • etc/: Global configuration
    • code/: Custom modules
    • design/: Themes
    • i18n/: Translation files
    • Bootstrap.php, autoload.php, functions.php: Must be included at the start of each execution
  • bin/: magento executable
  • dev/: scripts and tools for developers
  • lib/: Non-composer external libraries
  • vendor/: Composer dependencies, including the Magento core
    • module-*/: Magento 2 application code structured as modules
    • framework/: Magento 2 application code with no module structure
  • pub/: public content
  • setup/: Magento installatiom
  • var/: Temporary, disposable information

Module Structure

Not as strict as Magento 1. Folders are selected by convention and not requirement.

  • Block/: Block classes
  • Model/: Models and resource models
  • Setup/: Upgrade scripts and database migrations
  • view/: Module-specific layout, template and static files
  • frontend|adminhtml|base/
    • template - .phtml files
    • layout - Layout XML
    • web - static content such as images and css
      • images/
      • js/
      • ***.css**
  • registration.php: Used by composer's autoloader

Theme Structure

  • frontend|adminhtml|install/
    • Namespace/Theme
      • (Other_Module)/: Override other modules' view files by matching the path
      • composer.json
      • theme.xml

Modes

Set using an environment variable MAGE_MODE

Developer

  • Displays errors
  • Static view files are regenerated into the pub/static folder on every request
  • Detailed logging into var/report

Production

  • Fastest performance
  • Errors are logged to the filesystem
  • Static files are read from those generated by the CLI tool
  • Should have read-only permissions to the web server user

Default

  • Used when no mode is specified
  • Errors are logged to the filesystem
  • Static files are generated on a just-in-time basis

Maintenance

  • Triggered by the existance of a var/.maintenance.flag file, or Bootstrap::assertMaintenance();
  • Returns a 503 Internal Server Error
  • Can whitelist IPs in var/.maintenance.ip as a comma-seperated list

Cache

  • Handled by Magento\Framework\Cache
  • Default types are set in app/etc/env.php
  • Manage cache in Admin, or bin/magento cache:*, or clear var/cache/

Dependency Injection

  • Autoloads dependencies based on constructor arguments
  • A Preference applies globally
  • Assign a class in the module's di.xml for a particular class

Class Instantiation

  • Singletons should be passed in by DI
  • Entity classes should be passed in via Factories or Repositories
  • Factories are autogenerated and added to var/generation/(Path to Class).php

Object Manager

  • Is responsible for all instantiation
  • Manages dependencies
  • Handles what gets passed into class contructors' parameters
  • get() returns a singleton object ("shared instance")
  • create() returns a new instance
  • Can be included by adding a constructor argument \Magento\Framework\ObjectManagerInterface $objectManager
  • Shouldn't really be used directly though
  • Can resolve and autoload parameters that are \Name\Spaced\Paths\To\Classes
  • Uses di.xml from various modules to establish which class satisfies a requested interface

DI Configuration

  • app/etc/di.xml: Global application-wide configuration
  • (module)/app/etc/di.xml: Module-wide configuration
  • (module)/app/etc/(frontend|adminhtml)/di.xml: Area-specific configuration

<preference for="Path\To\Interface" type="Path\To\Class" />

1
2
3
4
5
6
type name="Path\To\Class"/
    arguments/
        argument/
            @name - constructor argument name
            @xsi:type - data type, such as object, string, array
            @shared - object types only. A false value means it's treated as a singleton

For array argument types:

1
2
3
            item/ - value for the data
                @name - key name?
                @type - another data type

Plugins

  • Change an class's behaviour without editing the class file itself
  • Cannot be used in final classes, private methods or classes created without DI
  • Results in an Interceptor class being generated into the var/generation/ folder

They can be used to:

  • Change a method's arguments
  • Change a method's return value
  • Override a method entirely (this risks breakages in other modules)

Declaring Plugins

In di.xml:

1
2
3
4
5
6
7
8
/config/
    type/
        @name - observed class or interface
        plugin/
            @name - a unique name for the plugin
            @type - by convention ModelName/Plugin
            @sortOrder - sorted by integer. Lower is higher priority
            @disabled - boolean value

Format

Create a class with a namespace, named Plugin

Types

  • Before listener: before(MethodName)
    • Used to perform actions before the method or to change the original method's arguments
    • Method arguments:
      • \Namespaced\Path\To\Original\Class $subject - An object of the original class
      • ($originalParameters) - any paramters from the original class
  • After listener: after(MethodName)
    • Used to perform actions after the method or to change the data returned from the method
    • Method arguments:
      • \Namespaced\Path\To\Original\Class $subject - An object of the original class
      • $result - The data to be returned to either the next in the chain, or the original caller
  • Around listener: around(MethodName)
    • Used to perform actions before and after the method, or to change both the arguments and the data returned from the method
    • Method arguments:
      • Namespaced\Path\To\Original\Class $subject - An object of the original class
      • \Closure $proceed - Will call the next plugin or method, eg $returnValue = $proceed();

Ordering

  1. The before-listener with the highest priority
  2. The around-listener with the highest priority
  3. The remaining before-listeners, ordered by priority
  4. The remaining around-listeners, ordered by priority
  5. The after-listener with the lowest priority
  6. The remaining after-listeners, ordered by inverse priority

Events

To fire an event:

1
2
3
4
5
6
$this->_eventManager->dispatch(
    'event_name',
    [
        'data' => $value
    ]
);

To register an observer in events.xml:

1
2
3
4
5
/event/
    @name - event name to be observed
    observer/
        @name
        @instance - class on which to call the execute(EventObserver $observer)

Module Configuration

Predefined config files

  • app/etc/config.php: Declaration of all modules
  • app/etc/env.php: Database connection details
  • (module)etc/config.xml: Stores > Config default values
  • (module)etc/system.xml: Stores > Config definitions
  • (module)etc/di.xml: Dependency injection config
  • (module)etc/events.xml: Module event observers
  • (module)etc/routes.xml: Routing config

core_config_data

  • Same as Magento 1 table
  • Allows for user-editable config changes
  • Backed by a module's etc/system.xml
  • Scopable: Global, Frontend and Admin
    • Config file should be placed in either etc/, or a frontend|adminhtml subfolder to scope them

Order of loading

  • Primary: only the config files needed to start the application
  • Global: Globally scoped files
  • Area-specific: Adminhtml/Frontend config

Any xpaths that match are merged in, and the values overridden on each level of merge.

Processing

  • Config is processed by \Magento\Framework\Config
    • DataInterface for value retrieval
    • ScopeInterface for scoping
    • FileResolverInterface for identifying which files should be read
    • ReaderInterface for reading config from its storage
    • This can be overridden by providing an interface implementation
  • XSD files can be created for validation before- and after merging
    • These can be the same file
  • Creating a new config type requires:
    • An XML file
    • An XSD Schema
    • Config PHP
    • A Config Reader
    • A Config Locator
    • A Coverter

Error Reporting

  • All errors (from Notice) cause exceptions
  • These are handled differently in different modes:
    • Developer mode shows a stacktrace
    • Default and Production show an error page, and log the error to var/report/