Subtree split of the Sage Theme Wrapper classes (see 'roots/sage')

README.md

💀 Sage Theme Wrapper for WordPress

This gist has been deprecated and moved to a repository and published on Packagist:
mcaskill/sage-theme-wrapper

Usage

Add the following filter to your theme's functions.php:

<?php

add_filter('template_include', function ($main) {
  if (!is_string($main) || !(string) $main) {
    return $main;
  }
  return \Roots\Sage\template_wrap(new \Roots\Sage\Template\Wrapper(basename($main)));
}, 109);

composer.json

{
  "name": "roots/sage-template-wrapper",
  "description": "A WordPress theme layout wrapper.",
  "keywords": [ "sage", "roots", "wordpress", "wp" ],
  "authors": [
    {
      "name": "Scott Walkinshaw",
      "email": "scott.walkinshaw@gmail.com",
      "homepage": "https://github.com/swalkinshaw"
    },
    {
      "name": "Ben Word",
      "email": "ben@benword.com",
      "homepage": "https://github.com/retlehs"
    },
    {
      "name": "Chauncey McAskill",
      "email": "chauncey@mcaskill.ca",
      "homepage": "https://github.com/mcaskill"
    }
  ],
  "require": {
    "php": ">=5.5.0"
  },
  "autoload": {
    "psr-4": {
      "Roots\\Sage\\Template\\": ""
    },
    "files": [
      "functions.php"
    ]
  }
}

functions.php

<?php

namespace Roots\Sage;

use Roots\Sage\Template\WrapperCollection;
use Roots\Sage\Template\WrapperInterface;

/**
 * @param WrapperInterface $wrapper
 * @param string $slug
 * @return string
 * @throws \Exception
 * @SuppressWarnings(PHPMD.StaticAccess) This is a helper function, so we can suppress this warning
 */
function template_wrap(WrapperInterface $wrapper, $slug = 'base')
{
    WrapperCollection::add($wrapper, $slug);
    return $wrapper->getWrapper();
}

/**
 * @param string $slug
 * @return string
 */
function template_unwrap($slug = 'base')
{
    return WrapperCollection::get($slug)->getTemplate();
}

Wrapper.php

<?php

namespace Roots\Sage\Template;

/**
 * Class Wrapper
 * 
 * @package   Roots\Sage
 * @author    QWp6t
 * @link      https://github.com/roots/sage
 * @copyright Copyright © Ben Word and Scott Walkinshaw
 * @license   https://github.com/roots/sage/blob/master/LICENSE.md
 */
class Wrapper implements WrapperInterface
{
    /** @var string Wrapper slug */
    protected $slug;

    /** @var string Template file that is being wrapped */
    protected $template = '';

    /** @var string[] Array of template wrappers; e.g., `base-singular.php`, `base-page.php`, `base.php` */
    protected $wrapper = [];

    /** @var string[] Cache template locations */
    protected static $locations = [];

    /**
     * Wrapper constructor
     *
     * @param string $template Template file, as from Template Heirarchy; e.g., `page.php`, `single.php`, `singular.php`
     * @param string $base Wrapper's base template, this is what will wrap around $template
     */
    public function __construct($template, $base = 'layouts/base.php')
    {
        $this->slug = sanitize_title(basename($base, '.php'));
        $this->wrapper = [$base];
        $this->template = $template;
        $str = substr($base, 0, -4);
        array_unshift($this->wrapper, sprintf($str . '-%s.php', basename($template, '.php')));
    }

    /**
     * @return string
     * @see getTemplate
     */
    public function __toString()
    {
        return $this->getTemplate();
    }

    /** {@inheritdoc} */
    public function getWrapper()
    {
        $wrappers = apply_filters('sage/wrap_' . $this->slug, $this->wrapper) ?: $this->wrapper;
        return locate_template($wrappers);
    }

    /** {@inheritdoc} */
    public function getSlug()
    {
        return $this->slug;
    }

    /** {@inheritdoc} */
    public function getTemplate()
    {
        $template = apply_filters('sage/unwrap_' . $this->slug, $this->template) ?: $this->template;
        return locate_template($template);
    }
}

WrapperCollection.php

<?php

namespace Roots\Sage\Template;

/**
 * Class Wrapper
 *
 * @package   Roots\Sage
 * @author    QWp6t
 * @link      https://github.com/roots/sage
 * @copyright Copyright © Ben Word and Scott Walkinshaw
 * @license   https://github.com/roots/sage/blob/master/LICENSE.md
 */
class WrapperCollection
{
    /** @var $this */
    protected static $instance;
    /** @var WrapperInterface[] $wrappers */
    protected $wrappers = [];

    /** Singleton */
    // @codingStandardsIgnoreStart
    private function __construct() {}
    private function __clone() {}
    // @codingStandardsIgnoreEnd

    /**
     * @return static
     */
    public static function instance()
    {
        isset(self::$instance) || self::$instance = new static;
        return self::$instance;
    }

    /**
     * @param WrapperInterface $wrapper
     * @param string $slug
     * @return $this
     * @throws \Exception
     */
    public static function add(WrapperInterface $wrapper, $slug = '')
    {
        $slug = $slug ?: $wrapper->getSlug();
        if (self::instance()->exists($slug)) {
            throw new \Exception("Wrapper $slug already exists.");
        }
        self::instance()->wrappers[$slug] = $wrapper;
        return self::instance();
    }

    /**
     * @param string $slug
     * @return $this
     */
    public static function remove($slug)
    {
        unset(self::instance()->wrappers[$slug]);
        return self::instance();
    }

    /**
     * @param string $slug
     * @return null|WrapperInterface
     */
    public static function get($slug)
    {
        return isset(self::instance()->wrappers[$slug]) ? self::instance()->wrappers[$slug] : null;
    }

    /**
     * @return string[] Slugs of wrappers in collection
     */
    public static function wrappers()
    {
        return array_keys(self::instance()->wrappers);
    }

    /**
     * @param $slug
     * @return bool
     */
    public static function exists($slug)
    {
        return isset(self::instance()->wrappers[$slug]);
    }
}

WrapperInterface.php

<?php

namespace Roots\Sage\Template;

/**
 * Interface WrapperInterface
 * 
 * @package   Roots\Sage
 * @author    QWp6t
 * @link      https://github.com/roots/sage
 * @copyright Copyright © Ben Word and Scott Walkinshaw
 * @license   https://github.com/roots/sage/blob/master/LICENSE.md
 */
interface WrapperInterface
{

    /**
     * Get wrapper template file
     *
     * @return string Wrapper template (FQPN of, e.g., `base-page.php`, `base.php`)
     */
    public function getWrapper();

    /**
     * @return string Wrapped template (FQPN of, e.g., `page.php`, `single.php`, `singular.php`)
     */
    public function getTemplate();

    /**
     * @return string Slug of the WrapperInterface; e.g., `base`
     */
    public function getSlug();
}