Stubs

A package to scaffold files, folders & content using variables

Use this package for PHP applications | CLI Here.

Installation

composer require dillingham/stubs

What is a stub?

A stub is a file or series of files that you wish to replicate on command. Furthermore, the file names, folder structure and content can be made unique with the use of variables. Save your stubs, groups of related files, in folders with a descriptive name and render them using methods documented below:

Jump to: Variables | Formatters | Stub Hooks | Laravel Support | Standalone CLI

Basic usage

Simply declare the source, output and which variables to render.

use Stub\Stub;

Process a folder and output files to another folder:

(new Stub)
    ->source('stubs/stub-1')
    ->output('projects/project-2')
    ->render($variables);

Variables

In render(), variables are declared as 'variable' => 'value'

[
    'resource' => 'User',
    'plural' => 'Users',
    'lower' => 'user',
]

The values become {{resource}} {{plural}} {{lower}} in the stubs. View examples.

Append .stub to filenames to avoid IDE errors, it is removed during render.

Variable Formatters

Sometimes multiple variations or formats of the same value are needed.

Thereforerender also accepts a class to compute stub variables.

The public method names become available as variables:

<?php

use Stub\Formatter;

class Example extends Formatter
{
    public function upper()
    {
        return ucwords($this->resource);
    }
    
    public function lower()
    {
        return strtolower($this->resource);
    }
}

The array passed in become available as class properties.

(new Stub)
    ->source('stubs/stub')
    ->output('projects/project')
    ->render(new Example([
        'resource' => 'User'
    ]));

This example turns resource into {{upper}} {{lower}} variables

Stub Hooks

Process a folder and send the files to a callback:

(new Stub)
    ->source('stubs/stub-2')
    ->output(function($path, $content) {

        // Called for each parsed file, instead of storing it
        // Useful for further modifications before you store it
        // or posting to an API like stubbing a GitHub repository

    })->render($variables);

Inspect & filter parsed files & content before outputting:

(new Stub)
    ->source('stubs/stub-3')
    ->output('project-name')
    ->filter(function($path, $content) {

        // called for each rendered file, BEFORE it is created
        // return false will prevent the output of that path
        // returning true or nothing will proceed normally

    })->render($variables);

Process a folder and listen to all created files with a callback:

(new Stub)
    ->source('stubs/stub-3')
    ->output('project-name')
    ->listen(function($path, $content, $success) {

        // Called for each file after the file it is parsed & stored
        // This may be used to log or output the results of the process
        // $success is either true / false depending on the storing result

    })->render($variables);

Create stubs

Creating stubs by hand is easy and works just as well. But you may find cases where you wish to generate stubs automatically. Such as, you really like a way a current project is structured and you want the ability to replicate it quickly in the future. That scenario is probably better accomplished via the CLI tool or artisan command, but its available via the class also.

Convert existing files into stubs for future use:

(new Stub)
    ->source('project')
    ->output('stubs/stub-name')
    ->create([
        'User' => 'resource',
        'Users' => 'plural',
        'user' => 'lower'
    ]);

The above code performs the following behavior:

• Renders all folders, files & content in project
• Search & replaces Users with {{name}}
• Replaces user with {{lower}} etc
• Appends .stub to filenames

(.stub avoids IDE errors)

Laravel Support

Use artisan commands & facades along with methods demonstrated above

You have immediate access to the following after you composer install:

Facade

Stub::source(resource_path('stubs/pattern-1'))
    ->output(app_path())
    ->render($variables);

Stub::source(app_path())
    ->output(resource_path('stubs/pattern-1'))
    ->create($variables);

Artisan

Create variables in a stub.json interactively:

php artisan stub:init values.json

Render the stub file(s) using variiables in values.json

php artisan stub:render <source> <output> values.json

Convert existing files into stub file(s) using values.json

php artisan stub:create <source> <output> values.json

Perform a clone + search and replace without stub files

php artisan stub:quick <source> <output>

Credits

Special thanks to the contributors

License

The MIT License (MIT). Please see License File for more information.