.. _extending_infrastructure:

#############################
Module infrastructure
#############################

Inside the module's bootstrap class you have several infrastructure objects available.

I recommend using a good PHP development environment like `PhpStorm <http://www.jetbrains.com/phpstorm/>`_ . Start your module as a new project and **include the root directory of Post Status Notifier** as a external library. Then you will get **autocompletion** for all internal infrastructure objects which helps a lot!

.. image:: _static/extend_ide.jpg
    :height: 618px
    :width: 1015px
    :scale: 100%
    :alt: PhpStorm

*************
Pluginmanager
*************

The Pluginmanager object is the central object in the plugin framework Post Status Notifier is built with. It is available in all important parts of the framework like for example the bootstrap object (:ref:`module_bootstrap`) of a custom module. The Pluginmanager object is always declared as ``$this->_pm``.

.. code::

    <?php
    $this->_pm->...

From the Pluginmanager you get access to all major infrastructure objects like **Pathinfo**, **Environment**, **Access**, **Config**, **Options** and more. All those objects can be retrieved from the Pluginmanager by **getter methods**.

.. image:: _static/extend_plugin_manager.jpg
    :height: 288px
    :width: 611px
    :scale: 100%
    :alt: Pluginmanager

*************
Access
*************

The Access object is very heplful when you want to **distinguish between page access types**. You can get it from the Pluginmanager's ``getAccess`` method.

.. code::

    <?php
    $this->_pm->getAccess()

The easiest example would be to load a CSS file **only if a plugin's admin page is accessed** as this file may manage some plugin page's layout and is irrelevant to all other WordPress backend pages. Then you can use the ``isPlugin`` method of the Access object, like this:

.. code::

    <?php
    if ($this->_pm->getAccess()->isPlugin()) {
        // load the CSS here
    }

If you not want to process some code on a **WordPress heartbeat** API request, use the Access object like this:

.. code::

    <?php
    if (!$this->_pm->getAccess()->isHeartbeat()) {
        // do not execute this code on heartbeat API requests,
        // because it does something that only makes sense on user page access
        // or causes some server load etc.
    }

A list of the Access object methods
===================================

+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| Method                    | Description                                                                                                           |
+===========================+=======================================================================================================================+
| isAdmin                   | True if a WordPress admin page is accessed, alias for is_admin()                                                      |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| isPlugin                  | True if it is an access to a PSN options page                                                                         |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| isAjax                    | True if it is an Ajax request                                                                                         |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| isPluginAjax              | True if it is an PSN internal Ajax request                                                                            |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| isDashboard               | True if it is an access to the WordPress dashboard page                                                               |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| isWidgetAdmin             | True if it is an access to the WordPress admin Appearance / Widgets page                                              |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| isHeartbeat               | True if it is an WordPress heartbeat API request                                                                      |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| isPostNew                 | True if it is an access to the create a new post page                                                                 |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| isPostEdit                | True if it is an access to the edit post page                                                                         |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| isModule($mod)            | True if it is an access to a PSN module page where $mod is the name of the module, e.g. isModule('example')           |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+


*************
Pathinfo
*************

The pathinfo object is very useful when you need information about the module's directory paths.

To get the pathinfo object use:

.. code::

    <?php
    $this->getPathinfo();

Pathinfo methods
================

The pathinfo objects features a bunch of public methods to retrieve the moudle's directories. This is a typical directory setting of a PSN module.

.. code:: jinja

    Example
    └ controllers/
    └ files/
      └ css/
        └ admin.css
      └ img/
      └ js
        └ admin.js
      └ tpl
    └ lang/
      └ psn_exm.pot
      └ psn_exm-de_DE.mo
      └ psn_exm-de_DE.po
    └ lib/
      └ Service/
        └ MyService.php
        ... more custom classes here ...
    └ views/
      └ scripts/
        └ psn-example/
          └ index.phtml
    └ bootstrap.php

+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| Method                    | Description                                                                                                           |
+===========================+=======================================================================================================================+
| getRoot                   | Points to the module's root directory                                                                                 |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getRootLib                | Points to the module's lib directory: ``[module_root]/lib/``                                                          |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getRootLang               | Points to the module's lang directory: ``[module_root]/lang/``                                                        |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getRootFiles              | Points to the module's files directory: ``[module_root]/files/``                                                      |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getRootCss                | Points to the module's CSS directory: ``[module_root]/files/css/``                                                    |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getRootJs                 | Points to the module's JS directory: ``[module_root]/files/js/``                                                      |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getRootImg                | Points to the module's image directory: ``[module_root]/files/img/``                                                  |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getRootTpl                | Points to the module's template directory: ``[module_root]/files/tpl/``                                               |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getBasename               | Retrieves the module's basename: bootstrap.php                                                                        |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getDirname                | Retrieves the module's dirname, e.g. "Example"                                                                        |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getDirnamePath            | Retrieves the module's dirname path, e.g. "/your/server/.../wp-content/plugins/post-status-notifier/modules/Example/" |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+

.. code::

    <?php
    // get the module root path
    $this->getPathinfo()->getRoot();

    // get the module lib path ([module_root]/lib/)
    $this->getPathinfo()->getRootLib();

    // get the module language path ([module_root]/lang/)
    $this->getPathinfo()->getRootLang();

    // get the module files path ([module_root]/files/)
    $this->getPathinfo()->getRootFiles();

    // get the module CSS path ([module_root]/files/css/)
    $this->getPathinfo()->getRootCss();

    // get the module JS path ([module_root]/files/js/)
    $this->getPathinfo()->getRootJs();

    // get the module image path ([module_root]/files/img/)
    $this->getPathinfo()->getRootImg();

    // get the module template path ([module_root]/files/tpl/)
    $this->getPathinfo()->getRootTpl();

    // get the module basename: bootstrap.php
    $this->getPathinfo()->getBasename();

    // get the module dirname: Example
    $this->getPathinfo()->getDirname();

    // get the module path to dirname: /your/server/.../wp-content/plugins/post-status-notifier/modules/Example/
    $this->getPathinfo()->getDirnamePath();

Using the pathinfo object, you can include the file [module_path]/lib/Service/MyService.php like this:

.. code::

    <?php
    // include the service class
    require_once $this->getPathinfo()->getRootLib() . 'Service/MyService.php';


*************
Environment
*************

The environment object gives you access to your module's environment values like URL paths and module properties.

To get the environment object use:

.. code::

    <?php
    $this->getEnv();

+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| Method                    | Description                                                                                                           |
+===========================+=======================================================================================================================+
| getUrl                    | Points to the module's base URL ``[blog_url]/wp-content/uploads/post-status-notifier/Example/``                       |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getUrlImg                 | Points to the module's image URL: ``[blog_url]/wp-content/uploads/post-status-notifier/Example/files/img/``           |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getUrlCss                 | Points to the module's CSS URL: ``[blog_url]/wp-content/uploads/post-status-notifier/Example/files/css/``             |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getUrlJs                  | Points to the module's JS URL: ``[blog_url]/wp-content/uploads/post-status-notifier/Example/files/js/``               |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getUrlFiles               | Points to the module's files URL: ``[blog_url]/wp-content/uploads/post-status-notifier/Example/files/``               |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getVersion                | Retrieves the module version                                                                                          |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getName                   | Retrieves the module name                                                                                             |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+
| getDescription            | Retrieves the module description                                                                                      |
+---------------------------+-----------------------------------------------------------------------------------------------------------------------+

.. code::

    <?php
    // get the module base URL
    $this->getEnv()->getUrl();

    // get the module CSS URL
    $this->getEnv()->getUrlCss();

    // get the module JS URL
    $this->getEnv()->getUrlJs();

    // get the module files URL
    $this->getEnv()->getUrlFiles();

    // get the module version
    $this->getEnv()->getVersion();

Using the environment object, it's very easy to **enqueue a CSS file** located in the module's subdirectory like ``files/css/example.css``:

.. code::

    <?php
    wp_enqueue_style('my-handle', $this->getEnv()->getUrlCss() . 'example.css', array(), $this->getEnv()->getVersion());