ItalyStrap Theme Json Generator

WordPress Theme Json Generator the OOP way

This is a WIP project and still experimental.

The idea is to generate a file theme.json from PHP because json sucks :D (just kidding)

With PHP you have the ability to split the file in multiple files, add comments, generate the content as you wish, PHP is not limited like json.

I'm experimenting this library as composer and WP_CLI plugin for generating the file.

Table Of Contents

• Installation
• Basic Usage
• Advanced Usage
• Contributing
• License

Installation

The best way to use this package is through Composer:

composer require italystrap/theme-json-generator --dev

This package adheres to the SemVer specification and will be fully backward compatible between minor versions.

Basic Usage

This library works on composer events:

function getSubscribedEvents(): array {
    return [
        'post-autoload-dump'	=> 'run',
        'post-install-cmd'		=> 'run',
        'post-update-cmd'		=> 'run',
    ];
}

That's it.

How it works

Basically, this plugin executes the following steps:

• This plugin searches for a custom callback you provide trough composer.json inside extra field.
• The callback needs to return an array with your theme config and accept a string argument where you get the path of the theme.
• And it generates the theme.json in the root folder of the theme you are developing.

Example project

The following is an example Composer project.

{
    "name": "italystrap/experimental-theme",
    "description": "Experimental theme",
    "type": "wordpress-theme",
    "require-dev": {
        "italystrap/theme-json-generator": "dev-master"
    },
    "extra": {
        "theme-json": {
            "callable": "\\YourVendor\\YourProject::your_callback"
        }
    },
    "repositories": [{
        "type": "vcs",
        "url": "https://github.com/ItalyStrap/theme-json-generator.git"
    }]
}

It is not yet on packagist and you have to add also the "repositories" field with the github url.

The callable must be a valid PHP callable and must return an array with your configuration following the schema provided from the documentation.

Example:

namespace YourVendor\YourProject;
/**
 * @argument string $path The path of the theme
 */
function your_callback( string $path ): array {
    // You can check against the $path argument in case you have parent and child theme.

    return [
        'version'   => 1,
        'settings'  => 	[
            'layout' => [
                'contentSize' => '620px',
                'wideSize' => '1000px',
            ],
        ]
    ];
}

And this will generate the following json:

{
  "version": 1,
  "settings": {
    "layout": {
      "contentSize": "620px",
      "wideSize": "1000px"
    }
  }
}

If you want to load manually using composer add your command inside the script field and load the ItalyStrap\\ThemeJsonGenerator\\ComposerPlugin::run method like below:

{
  "scripts": {
    "your-command": [
      "ItalyStrap\\ThemeJsonGenerator\\ComposerPlugin::run"
    ]
  }
}

And then run:

composer run your-command

WP_CLI command

As I said this is also a WP_CLI plugin, for now it is all included in this library for testing purpose, maybe I can split in other library if I see the need of doing that.

For using as WP_CLI command you have to create a file wp-cli.local.yml or wp-cli.yml in the root of your theme or better in the root of the WordPress installation.

Inside that file add this line for adding your custom callback:

THEME_JSON_CALLABLE: '\YourVendor\YourProject\your_callback'

And in the command line just use the command:

wp theme-json generate

This will generate the theme.json on the root of the active theme, parent or child. If you want to generate the theme.json for both add the option --parent

wp theme-json generate --parent

And remember to check inside the callback the path to provide the right config for the theme you want to generate the file.

This command is still experimental, could be changed in future.

Advanced Usage

Contributing

All feedback / bug reports / pull requests are welcome.

License

Copyright (c) 2021 Enea Overclokk, ItalyStrap

This code is licensed under the MIT.

Credits