README

Introduction
Requirements
Installation
Usage
Contributors
Security
Changelog
License

Introduction

The Stubborn package enhances the PHP development workflow by providing a set of customizable stubs. Stubs are templates used to scaffold code snippets for various components like models, controllers, and migrations. With Stubborn, developers can easily tailor these stubs to match their project's coding standards and conventions. This package aims to streamline the code generation process, fostering consistency and efficiency in PHP projects. Explore the customization options and boost your development speed with Stubborn.

Requirements

PHP >= 8.0

Installation

You can install the package with Composer, but make sure to add this repository (as type git) in your composer.json. When this package is available on packagist, you can skip this step (and it won't be mentioned here). Once the repository is added, run:

composer require tylerdak/stubborn

You don't need to publish anything.

Usage

Create a stub file

First of all, create a stub file called model.stub:

touch model.stub

Add some code to that, like this:

<?php

namespace {{ NAMESPACE }};

class {{ CLASS }}
{
    
}

How to Use Stubborn

In order to use Stubborn, you need to import the Stubborn\Stub class:

use Dakin\Stubborn\Stub;

Stub::class;

`from`

First thing, you need to use the from method to give the stub path:

Stub::from(__DIR__ . 'model.stub');

`to`

Next, you'll want to specify the destination directory of the stub file:

Stub::from(__DIR__ . 'model.stub')
    ->to(__DIR__ . '/App');

`name`

You can set the stub file with this, but make sure to leave out the stub extension:

Stub::from(__DIR__ . 'model.stub')
    ->to(__DIR__ . '/App')
    ->name('new-model');

`ext`

You can determine the stub extension:

Stub::from(__DIR__ . 'model.stub')
    ->to(__DIR__ . '/App')
    ->name('new-model')
    ->ext('php');

`replace`

The replace method takes two parameters, the first one is the key (variable) and the second one is the value. The value will be replaced with the variable:

Stub::from(__DIR__ . 'model.stub')
    ->to(__DIR__ . '/App')
    ->name('new-model')
    ->ext('php')
    ->replace('NAMESPACE', 'App');

`replaces`

The replaces method takes an array. If you want to replace multiple variables you can use this method:

Stub::from(__DIR__ . 'model.stub')
    ->to(__DIR__ . '/App')
    ->name('new-model')
    ->ext('php')
    ->replaces([
        'NAMESPACE' => 'App',
        'CLASS' => 'MyClass'
    ]);

`generate`

To generate the stub file, you need to use the generate method at the end of the chain to generate stub file:

Stub::from(__DIR__ . 'model.stub')
    ->to(__DIR__ . '/App')
    ->name('new-model')
    ->ext('php')
    ->replaces([
        'NAMESPACE' => 'App',
        'CLASS' => 'MyClass'
    ])
    ->generate();

If you're following along, the final file should be named new-model.php and look something like this:

<?php

namespace App;

class MyClass
{
    
}

Modifiers

Stubborn adds support for modifiers. Modifiers let you use a single replace string in multiple forms. Here's an example... Let's say you have a class stub that can introduce itself:

<?php

namespace App;

class {{ NAME }}
{
    public function introduce(): string {
        return "I am a {{ NAME }}";
    }
}

This is fine, but maybe I want the class to shout its name in ALL CAPS. Instead of declaring that behavior from my Stub generation code, I can put that intention directly in the stub file.

Mind you, this particular use case would benefit more from not having the class name statically declared twice, but for demo purposes...

<?php

namespace App;

class {{ NAME::studly }}
{
    public function introduce(): string {
        return "I am a {{ NAME::upper }}!";
    }
}

There's a new Str class that's been adopted from the Laravel framework to offer several helpers as modifiers. Most of the single parameter methods from that class can be used as modifiers by adding ::methodName after the variable name. These modifiers can also be chained together: {{ NAME::upper::trim }}.

In addition, you can add your own modifiers by editing the Stub::modFunctions associative array. You can pass in the modifier name as the key and a function accepting a string as the value:

use Dakin\Stubborn\Stub;

Stub::modFunctions['repeat'] = fn ($theString) => $theString . $theString;

Now, stubs with {{ VAR_NAME::repeat }} will repeat the replace value once.

Setting a stub folder

It's likely you'll have a single place where you want to keep all of your stubs ({project_path}/stubs, for example). It can be a pain to keep providing that folder path as context when generating stubs.

$stubber = Stub::from('path/to/my/stubs/the-actual.stub');

Instead, you may set the stub folder a single time using the static setFolder method.

// During setup...
Stub::setFolder('path/to/my/stubs');

// Later on...
$stubber = Stub::from('the-actual.stub');

A couple notes about this:

setFolder checks that your path is, in fact, a directory. Disable that behavior by setting the safe parameter to false.
Related static methods resetFolder and folder are available for you to, respectively:
- Set the stub folder to null, restoring standard from behavior
- Get the current stub folder value
setFolder returns a boolean representing success/failure. If the path given is not a directory and $safe is set to true, it will return false. Otherwise, it returns the stubFolder value casted to a bool.

Contributors

The crew at Binafy did most of the heavy lifting on this with their Laravel-embedded version of this package.

Security

If you discover any security-related issues, please email tyler@dakin.one instead of using the issue tracker.

License

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

dakin / stubborn

Maintainers

Details