PHPackages websemantics/builder-extension - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. websemantics/builder-extension ActiveStreams-addon[Utility & Helpers](/categories/utility) websemantics/builder-extension ============================== Pyro 3 Addons scaffolder for maximum coding pleasure 1.1.7(7y ago)122084[9 issues](https://github.com/websemantics/builder-extension/issues)MITPHP Since Aug 9Pushed 7y ago3 watchersCompare [ Source](https://github.com/websemantics/builder-extension)[ Packagist](https://packagist.org/packages/websemantics/builder-extension)[ Docs](http://websemantics.ca)[ RSS](/packages/websemantics-builder-extension/feed)WikiDiscussions master Synced today READMEChangelog (10)Dependencies (3)Versions (24)Used By (0) ``` /'\ / \ / \ _ / ..' \_ /\/'\ / \ / './ \ / \ _/ \ / \ _ / oO \ /'\ / '._'\ / \ / \ / /''\ / \ / \ / / \ / \ / \_ ..' \ / \ / \__ / / \ / \__/ \ \/ \ / / \/__ \ \ \ \/ __/ \ \ \ \ / \ \ )))) \__ _________ _______ __ooO_(O o)_Ooo____ | \ \ / | (_) \\===========\===========\ | __ \ \ / | __ | | | | |__) \ V /| |__) | | | | |\ / | < ┌┴┐ ┌┴┐ | ___/ | | | \ _ \ \ / | | | | | | |\ \ | \_| | | \_ | | | | | | \ \ \___/ __ \ `-_ |_______| |_________| |______| |______| / \ ''-. \ ____ __ __ ____ _ ___ ___ ____ / / \ \ | \ | | || || | | \ / _|| \ | | | | | () )| | | | | | |\\\\ \ / |_ | () ) \ \ / / | || | | | | | ( oo) () || _|| / \ `-..-' / | () || : | | | | (_) || |_ | \ - -- '-_ _-' |_____| \__,_||____||____||_____||_____||__|\_| `------' Addons scaffolder for maximum coding pleasure - -- --------- -- - ``` > This PyroCMS 3 extension once installed becomes your coding companion to scaffold Pyro modules, themes, extensions and [stream entities](#stream-entities). Motivation ---------- [](#motivation) Here are some of the thoughts and reasons behind building the builder extension, From the prospective of a developer, Pyro 3 reduces complexity and introduces simplicity and structure into building large scale web applications with its [modular design](https://en.wikipedia.org/wiki/Modular_design), Modules, Extension, etc and data structure abstraction ([ATD](https://en.wikipedia.org/wiki/Abstract_data_type)), realized in the [Stream Platform](https://github.com/anomalylabs/streams-platform), However, with structure comes repetition and the need to use boilerplate code combined with predefined set of steps to integrate that with your application. Usually this is all covered in the documentation, but who has time for that? This extension tries to remove some of that tedious work so that the developer can focus on writing business logic of the application. To achieve that, the builder offers a number of commands and provide scaffolders for the different aspects of building a Pyro application, For examples, once installed, the extension will scaffold a software structure called [Entity](#stream-entities) for every stream migration generated with the `make:stream` command. The code generated includes `Models`, `Repositories`, `Table Builders`, `Form Builders`, `Admin Controllers`, `Seeders` to name a few. And with the help of a [PHP parser](https://github.com/nikic/PHP-Parser), it will configure the module classes with routes, bindings, language file entries and even seeding and even helper functions. Install ------- [](#install) In your project folder, require the extension with `composer` and then install as follows, ``` composer require websemantics/builder-extension php artisan extension:install websemantics.extension.builder ``` Getting Started --------------- [](#getting-started) The first command to use when developing a Pyro application with the builder extension is `make:addon`. The default `make:addon` command has been extended to enable [*template-based*](#make-template) code scaffolding. Make Addon ---------- [](#make-addon) Use the `make:addon` command as per usual, [documentation](https://www.pyrocms.com/documentation) to create modules, themes and other addon types. However, there are two new concepts that this extension introduces, 1- A [default template](#environment-variables) is prescribed for each addon type (if [available](#list-templates)) that the builder downloads and uses to generate code. 2- Each template come with a schema (a list of variable, for example, `vendor`, `slug` etc) that the builder uses to scaffold code. These variables have default values but the user will be ask to change their values interactively unless the `--defaults` option is used to [skip](#make-addon) the process. #### Make Module [](#make-module) ``` php artisan make:addon vendor.module.name ``` The previous command creates a module based on the [default module](https://github.com/pyrocms-templates/default-module) template. The downloaded module template will be cached at `storage/streams/default/builder/default-module`. **NOTE**: A fields migration file will not be generated as per Pyro 3 default `make:addon` command behaviour. The builder extension generates a separate fields migration file for each [stream migration](#make-stream) instead. #### Make Theme [](#make-theme) There are two templates to generate a theme addon, an [*admin*](https://github.com/pyrocms-templates/pyrocms-theme) and a [*front-end*](https://github.com/pyrocms-templates/starter-theme). ``` php artisan make:addon vendor.theme.name --force --admin ``` The `--force` option forces the extension to download a fresh copy of the template and `--admin` to create an *admin* theme. Omit `--admin` option to create a *front-end* theme. #### Make Addon [](#make-addon-1) The previous uses of `make:addon` make assumptions about the template to use when creating the addon ([default module](https://github.com/pyrocms-templates/default-module), [pyrocms-theme](https://github.com/pyrocms-templates/pyrocms-theme) etc). This behaviour can be changed by providing an optional template name, `default-module` as follows, ``` php artisan make:addon websemantics.module.name default-module --defaults ``` The `defaults` options disables the user interactive mode and forces the template defaults. This command also supports `--shared` and `--migrate` options. #### Make Template [](#make-template) A template is like a recipe that the extension uses to scaffold code for an addon type, or any software package for that matter, ``` php artisan make:addon websemantics.module.name --template ``` The previous command will create a template for the specified addon type, `defaults` and uses `vendor` and `slug` provided as default values for the template schema. More details about templates and how to use them locally can be found at [template-template documentation](https://github.com/pyrocms-templates/template-template). List Templates -------------- [](#list-templates) This command will list all available addon templates from the [registry](#the-registry), ``` php artisan builder:list ``` Result, ``` ____ __ __ ____ _ ___ ___ ____ | \ | | || || | | \ / _|| \ | () )| | | | | | |\\\\ \ / |_ | () ) | || | | | | | ( oo) () || _|| / | () || : | | | | (_) || |_ | \ |_____| \__,_||____||____||_____||_____||__|\_| Addons scaffolder for maximum coding pleasure Builder Commands: - make:addon Create an addon from a template if avilable - builder:list List available templates from the registry - builder:clear Clear cache and locally stored templates Retrieving a list of available templates +-------------------+-----------------------------------------------------------------------+---+ | Name | Description | ★ | +-------------------+-----------------------------------------------------------------------+---+ | default-module | The default module template for Pyro Builder | 2 | | default-skin | The default skin template for PyroCMS Plus Theme | 0 | | pyrocms-theme | A customizable release of the official PyroCMS admin theme | 2 | | starter-theme | A customizable release of PyroCMS started theme | 4 | | template-template | The default Pyro Builder template for building Pyro Builder templates | 3 | +-------------------+-----------------------------------------------------------------------+---+ ``` Notice how each template has one star only! :/ Well, you can change that by liking these repos [here](https://github.com/pyrocms-templates) :) Clear Cache ----------- [](#clear-cache) To clear the builder cache and delete all locally downloaded templates run the following command, ``` php artisan builder:clear ``` Make Stream ----------- [](#make-stream) The builder introduces new abilities to `make:stream` command, for example, to specify stream properties and fields, Using the example provided in [Auto-pyro](https://github.com/websemantics/auto-pyro) to create a [todo module](https://github.com/websemantics/auto-pyro/blob/1.0.0/local.properties#L97), the following will create a `Task` stream and all of it's assignments, ``` php make:stream 'task:tc(name),name,description:t(anomaly.field_type.textarea),completed:t(anomaly.field_type.boolean)' websemantics.module.todo ``` Instead of specifying the stream `slug` only, `make:stream` command now accepts a comma-separated list of fields following the stream slug and properties. The following is a complete list of options available to use with streams and field. Option values - if applicable - are provided between parentheses (as in the example above), PropertyShorthandInheritabletitle\_column`tc`◻️type`t`◻️required`r`◻️unique`u`◻️searchable`s`◻️locked`l`◻️translatable`trans`✅trashable`trash`✅sortable`sor`✅The `Inheritable` column indicates the properties a stream would inherit if one of its fields has it set to true. For example, ``` # First, generate the module php artisan make:addon vendor.module.name # Then generate the stream migration files php artisan make:stream 'comment:title_column(name),name:trans' vendor.module.name # This can also be expressed as php artisan make:stream 'comment:title_column(name),name:translatable(true)' vendor.module.name # Or as, php artisan make:stream 'comment:title_column(name):translatable(true),name:type(anomaly.field_type.text):translatable(true)' vendor.module.name ``` The previous will generate a stream migration as follows, ``` protected $stream = [ 'slug' => 'comment', 'title_column' => 'name', 'translatable' => true ]; protected $assignments = [ 'name' => [ 'translatable' => true ] ]; ``` If the `type` property of a field is not set, the builder extension will assume `anomaly.field_type.text` as default. #### Environment Variables [](#environment-variables) All environment variables used by the extension are listed here, VariableDescriptionDefault*BUILDER\_REGISTRY*The default Builder Extension registry`pyrocms-templates`*BUILDER\_DEFAULT\_TEMPLATE*Template of templates to create an addon template`template-template`*BUILDER\_DEFAULT\_MODULE*Default template for modules`default-module`*BUILDER\_DEFAULT\_ADMIN*Default template for admin themes`pyrocms-theme`*BUILDER\_DEFAULT\_FRONT*Default template for front-end themes`starter-theme`*BUILDER\_TTL*Time used to cache an API call`60` minutes*BUILDER\_PATH*Path to the local storage to cache templates`builder`*BUILDER\_ARCHIVE\_URL*Url to the compressed file of the template repo`url-template`*BUILDER\_TMP*Temporary folder to uncompress zip files`folder`*MIGRATION\_PADDING*Padding between arrays `(key,value)`s in migration file`30` charsConfiguration file can be found at, `./resources/config/config.php`. Overridden in project `.env` file to change the default behaviour. Stream Entities --------------- [](#stream-entities) In addition to scaffolding addons from builder templates, the builder offers generating stream entities from migrations. An Entity is a representation of an [Object Type](https://en.wikipedia.org/wiki/Object_type_(object-oriented_programming)) which may correspond with a Stream. For example, a **Person**, a **Company** or an **Animal** can all be represented by Streams and Entities. The code generated for an entity includes an `Entity Model` and `Repository`, `Plugin`, `Seeder`, `Contracts`, `Table Builder` and `Form Builder`. Please read the following section for a better understanding of this process. Building a Blog --------------- [](#building-a-blog) The source code of this example is available [here](https://github.com/websemantics/blog). The idea is to build a module with the least amount of effort and experience how the builder extension does its work, - Create and install a new PyroCMS project and name it `blogger`, ``` # first, create a fresh pyro project and change folder, composer create-project pyrocms/pyrocms --prefer-dist blogger cd blogger # install from the command line, php artisan install ``` - Install the builder extension, ``` composer require websemantics/builder-extension php artisan extension:install websemantics.extension.builder ``` - Create a new module, `blog` ``` php artisan make:addon websemantics.module.blog ``` - Create `posts` stream and its fields, ``` php artisan make:stream 'posts:tc(title),title:r:u,content:r' websemantics.module.blog ``` The result, ``` protected $stream = [ 'slug' => 'posts', 'title_column' => 'title' ]; protected $assignments = [ 'title' => [ 'required' => true, 'unique' => true ], 'content' => [ 'required' => true, ] ]; ``` This will also generate a seeder template for this entity (see below), - Add seeder data to, `blog/addons/default/websemantics/blog-module/resources/seeders/post.php` (singular file name) ``` ['title' => 'Laravel', 'content' => 'PHP framework'], ['title' => 'PyroCMS', 'content' => 'PHP CMS'] ``` The content must be a list of entry values without `