Download the PHP package brain/occipital without Composer

On this page you can find all versions of the php package brain/occipital. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of brain/occipital

Informations about the package occipital

Occipital

Occipital

Build Status

Occipital is a Brain module for style and scripts management.

It allows a better way to enqueue scripts and styles in WordPress.

Occipital, like others Brain modules is not a full-plugin, its a package to be embedded in larger projects.

However, embed in a theme or in a plugin is just matter of, literally, 3 lines of code and there is a step-by-step guide to include Occipital in a theme.

What's wrong with standard styles and scripts handling in WordPress?

Have a look to related blog post.

Features

Quick Start

All the things in Occipital can be done via API class: Brain\Assets.

Before do any call, you should wait for 'brain_loaded' hook, or 'init' if you prefer core hooks.

Below an example with all the methods available for scripts (only 2 are required):

addScript method allows to add script in frontend, backend and login pages. To add asset in a specific place is possible:

API methods return the instance of asset object just added, or a WP_Error if something goes wrong.

For styles there are similar methods: addStyle, addFrontStyle... and so on.

Improvements against core are:

Requirements

Installation

You need Composer to install the package. It is hosted on Packagist, so the only thing needed is insert "brain/occipital": "dev-master" in your composer.json require object:

After that, in your console, navigate to package folder and type

Don't forget the --no-dev flag before using in production, otherwise all the dev dependencies with related autoload stuff will be loaded on every page load, substantially slowing down your page loading.

Compatibility

Occipital is 100% compatible with core workflow and to all themes and plugins that uses the proper, recommended way to enqueue assets to WordPress sites.

Code that not use recommended hooks or directly print style and script tags to page markup is not compatible with Occipital, and anyway they are doing it wrong.

Documentation

API class

Occipital comes with an API that ease its usage, without having to get, instantiate or digging into package objects. The API class is Brain\Assets.

All operations in Occipital can be done via its API, as static methods, e.g.

addStyle above (just like all the other API methods) is not a "real" static method: API class works just as a proxy to proper instantiated objects methods. It's the same concepts behind Laravel facades, but instead of Laravel IoC, Occipital uses Brain module, that is a Pimple container with some WordPress-specific sugars.

Bootstrap

Before being able to use any Occipital API method we have to be sure that it is fully loaded. As a Brain module, we can do that using specific "brain_loaded" hook, but core "init" is fine too.

Moreover, we need to bootstrap Occipital, just after Composer autoload has been loaded. This is all you need to do before to use Occipital API:

Adding assets

Occipital supports adding assets (styles and scripts) in 3 places: frontend, backend and login page.

Main API methods to add assets are: addStyle and addScript.

These methods signature is:

$handle is the style / script id, it must be unique, and is the only required argument.

$args is an array of arguments for the assets, more on this later in the page.

$where is the specific place where you want to add the asset, it can be:

If nothing is given for $where than "all" is assumed, so the asset will be added in frontend, in backend and in login pages.

To add assets on a specific place there are specific methods:

Arguments summary

Second argument for add* methods is $args, an array that can be used to set all the arguments for the asset.

Below there is the complete list of supported keys:

As you can see, most of the arguments pairs with core arguments for wp_register_* and wp_enqueue_* functions, or with other core functions (wp_add_inline_style, wp_localize_script).

Only new arguments are "condition" and "provide" that are further explained later in this page.

Fluent interface

Passing configuration arguments to a function via an array is a very common task in Wordpress world. However I for myself, and probably others, thinks that fluent interface used by some popular PHP frameworks is very easy to use and read. This is the main (but not the only) reason why Occipital supports this pattern.

Essentially, there is one setter method for each argument (named in the exact way of related key in arguments array) and every setter return the asset object itself, allowing to call another setter in a "chained" way (do you know jQuery? Something like that)..

Example:

localizeData (or after for styles) can be called more than once, to send more objects to javascript, example:

Consider that setter methods have not to be called in a "chained" way, they can be called to an instance of asset object at anytime.

Thanks to the fact that an asset object can be retrieved in every part of the code, (how-to is explained later in this page) this pattern gives a lot of flexibility that the "array way" can't give.

Only note that calling setters after an asset is printed to page, make no sense and has no effect, of course.

Condition callback

A lot of times, an asset should be added only under specific conditions, this is main reason why assets in WordPress have to be added hooking specific actions: to be sure that a context is available to choose if add the asset or not.

Occipital solve the problem with a different approach: it allow to set a callback as condition, and it is evaluated only at right timing, no matter when the asset is added to the stack. In this way is possible to avoid the addition of asset in 2 separate function wp_register_* and wp_enqueue_* and is also possible pass a context to condition callback to facilitate developer works.

This is how a condition may look like for frontend:

and for backend

The condition callback receives 3 arguments:

Provide

Provide allows to set an array of assets that are "contained" in the asset being added, it will avoid WordPress to load that files while ensuring compatibility with third party code.

A big problem with WordPress assets is the high number of HTTP requests a typical page has (have you read the blog post?).

If an user has 20 plugins installed and half of them add a script and a style, and a couple of styles and scripts are added by theme, a page loading will require 24 http requests to load everything.

That's quite crazy.

Occipital approach is simple: it allows site owners to enqueue concatenated scripts and styles, and declare wich assets are shipped in the "big" file, to ensure compatibility with any other code.

As example, let's assume in a site header there is

site owner can use Occipital to do something like this:

And, like a magic, 4 http requests turned 1 coming from a CDN.

Of course concatenated style is not forced to contain the styles declared as provided in the exact version shipped by plugins, and actually is not forced to contain them at all, it's just a way to force WordPress to not add them, even if other code will enqueue them or declare them as dependency.

E.g. let's assume in the same site, the owner want to try a plugin and this plugin has in its code:

The style from this plugin will be enqueued as expected, thickbox will be added because declared as dependency and not provided by any other style, but 'plugin1-style' will not be added, because declared as provided.

Gotchas for "provided" styles on login pages

If a site owner use provide Occipital feature to include, in a custom concatenated file, some of the styles core uses for login page (their handles are 'buttons', 'open-sans', 'dashicons', 'login') it will not work. Reason is that core styles in login pages are printed with a direct call to wp_admin_css that can't be filtered, and also run before "login_enqueue_scripts" so any style added using that hook are taken into account when core styles are already printed. The provide feature works as expected for custom styles in login pages.

Big warning for developers

Until here I always said that provide feature should be used by site owners. Never mentioned plugin / theme developers.

Reason is that plugin / theme developers should use provide feature with a lot of care.

Let's assume a plugin uses following code:

It means that the script added by plugin contains a version of jQuery and jQuery UI.

What happen if another plugin provides that scripts again? Only thing Occipital can do in that case is to enqueue again those scripts, because it can't be able to remove a portion from a concatenated file...

However, developers can benefit from provide feature in assets management for own plugins.

Let's clarify with an example.

Let's assume a plugin have a free version and premium addon. Free version needs a style and a script, added like so:

Premium version can do:

In this way, users of premium addon, instead of 4 http request will have only 2. Awesome, isn't it?

Sure, the owner of the site where plugin is installed can embed 'awesome_plugin_premium_script' in a big concatenated file, together with other plugins scripts, but great majority of users will not do that, and halve HTTP requests for a plugin is a good thing, anyway.

Another use case can be include parent theme style from child theme, avoiding @import in CSS and ensuring compatibility with any style that has parent theme CSS as dependency.

In summary, developers should use the "provide" feature to reduce HTTP requests of own plugins or theme assets, but never use it to ship core assets.

Removing assets

Sometimes one needs to remove assets. In Occipital (at the moment) you can remove only assets added using Occipital.

That is done via removeStyle and removeScript API methods.

Only argument accepted by thos methods is the asset handle. Of course to remove an asset, one needs to be sure that the callback that adds it already ran. Unlike WordPress, Occipital provides a specific hook for the scope (or better, 4 hooks): "brain_assets_remove"that is fired in all "sides" (frontend, backend and login pages) and other three side-specific hooks. More info in the Occipital hooks paragraph.

Get and set assets properties

Let's assume somewhere in a plugin code there's an asset added like so

Everywhere (same plugin, another plugin, theme) is possible to get the asset that previous line added and retrieve information about it and also modify it, if needed.

That is done with the 2 API methods: getStyle and getScript.

In following example I'll get the script added above and

This is the Occipital code

Doing same thing using core would required:

Difference is not only the number of lines of code, difference is also in

Regarding Occipital API, in the example above there is a getSrc() method: it is only one of the getter available for assets objects, in facts, there is a getter for every setter, so we have:

In "Fluent interface" paragraph there are different names for setters, that's because all setters have a shortened alias without the leading set and with first letter lowercased. However, to use "full" setter names in fluent interface is perfectly fair.

Assets classes

In different parts of this page I refer to "asset class", and "asset object" in fact, in Occipital, every assets added is an object (just like in core, to be honest).

The default class for styles is Brain\Occipital\Style, for scripts is Brain\Occipital\Script.

I said "default" because is possible for a developer write a custom implementation of the 2 interfaces: Brain\Occipital\StyleInterface and Brain\Occipital\ScriptInterface.

Both extends Brain\Occipital\EnqueuableInterface and all of them are pretty documented in code with phpDoc comments.

Get info for non-Occipital assets

As proven in previous paragraph, getting information for enqueued assets in WordPress is not very easy nor straightforward. Occipital provides a way to create an Occipital asset object starting from any non-Occipital registered asset, in that way is possible to use Occipital getters to get information.

That is done instantiating an Occipital asset object and calling the fillFromRegistered() method on it.

As example, somewhere there is a piece of code like the following:

Having Occipital installed we can:

$data will be an array with a single element: a plain object (stdClass) with 2 properties:

Reason why it is an array is that wp_localize_script (just like setLocalizeData in Occipital) can be called more than once on scripts handle, in that case the array will contain more objects.

I can assure you that doing same thing with core functions is not so easy: as example, did you know that WP stores the localization data for scripts in string form (a new-line separated string, in case there were more than one wp_localize_script scripts)?

In current Occipital version only getters can be used (any setter will change properties on the created object but will not affect behavior of the asset enqueued).

Error handling

All the add* API methods return an asset object (see previous paragraph) that can be used for all purposes: (debug, getting info, editing...).

Of course, all the "chainable" setter methods return the same instance (internally they returns $this).

Hower when something goes wrong, any method may return a WP_Error object.

You may reasonably think that when using fluent interface if a method at start or in the middle of the methods "chain" returns an error object, next method will cause a fatal error: well, that's not true.

This little "magic" is done thanks to a custom Error class that extends WP_Error making it "chainable": everitime a non-existing method is called on it, an error message is added to object errors stack (WP_Error supports multiple errors) then the object return itself.

Thank to the fact that custom error class extends WP_Error, it can be checked via is_wp_error and is capable of run all its methods.

Occipital hooks

There are several custom action hooks fired by Occipital, they can be divided into 2 groups "ready hooks" and "Printing hook".

Ready hooks

They are:

First three are specular to WordPress "wp_enqueue_scripts", "admin_enqueue_scripts" and "login_enqueue_scripts". However, when using Occipital API is possible to add assets at any time that goes from init to wp_print_styles (when assets going to be printed) so there is no need to use one of this hooks, reason for their existence is that all of them (just like the generic "brain_assets_ready", that runs just before any of the first three) pass to hooking callbacks the instance of assets container class Brain\Occipital\Container that can be used to add hooks without use the API and other (currently undocumented) advanced operations.

"brain_assets_remove" and the three *`"brain_assetsremove"** hooks, as guessable, can be used to remove added assets. In fact, to remove an asset, we need to be sure that the function that adds it has been processed. In WordPress, usually, a safe place iswp_print_styles, Occipital provides a specific hooks for the scope. The generic"brain_assets_remove"` is available everywhere, moreover there is one hook for any supported "side".

Last hook in the series, "brain_assets_done" is fired when the enqueuing process has been completed. It’s mostly used internally, but it is a safe place to get information about enqueued assets, as example assets whose condition callback have returned a false value have been discarded when that hook is fired.

Printing hooks

They are:

"brain_doing_style" is fired immediately before a style <link> tag is printed to page, and "brain_style_done" is fired immediate after that.

"brain_doing_script" is fired immediately before a script <script> tag is printed to page, and "brain_script_done" is fired immediate after that.

Note that WordPress does not provide nothing similar, and sometimes a feature like this is required, e.g to print a no conflict call immediately after a script has been added.

License

Occipital own code is licensed under GPLv2+. Through Composer, it installs code from:

All versions of occipital with dependencies

PHP Build Version
Package Version
Requires php Version >=5.4
brain/brain Version ~0.1.0
brain/support Version ~0.1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package brain/occipital contains the following files

Loading the files please wait ....