library phint

adhocore/phint

Initializes new PHP project with sane defaults using templates

adhocore/phint

Initializes new PHP project with sane defaults using templates. It scaffolds PHP library &/or project to boost your productivity and save time., _(*1)

For already existing project, run with --sync flag to add missing stuffs, see phint init., _(*2)

Once you have files in your src/ or lib/ you can run phint docs to generate API like documentation in .md format and phint test to generate basic test stubs with all the structures already maintained., _(*3)

It helps you be even more lazier! phint is continuously evolving and the plan is to make it big., _(*4)

, _(*5)

, _(*6)

Installation · Features · Autocompletion · Usage · phint init · phint update · phint docs · phint test · Templating, _(*7)

Phint is powered by adhocore/cli, _(*8)

Installation

Requires PHP7., _(*9)

Manual

Download phint.phar from latest release. And use it like so php /path/to/phint.phar [opts] [args]. Hmm not cool. See Command section below., _(*10)

Command

# get latest version (you need `jq`)
LATEST_PHINT=`curl --silent "https://api.github.com/repos/adhocore/phint/releases/latest" | jq -r .tag_name`

# download latest phint
curl -sSLo ~/phint.phar "https://github.com/adhocore/phint/releases/download/$LATEST_PHINT/phint.phar"

# make executable
chmod +x ~/phint.phar
sudo ln -s ~/phint.phar /usr/local/bin/phint

# check
phint --help

Features

• generate dot files the likes of .gitignore, .travis.yml, . editorconfig etc
• generate LICENSE, README.md, composer.json
• generate CHANGELOG.md stub, CONTRIBUTING.md guide, ISSUE_TEMPLATE.md and PULL_REQUEST_TEMPLATE.md
• generate binaries if any
• git init
• interactively ask and install all the dev and prod deps
• generate phpunit.xml, test bootstrap.php
• generate test stubs for all classes/methods corresponding to src (phint test)
• generate docs for all public class/methods
• export templates to chosen path so it can be customized (phint export)
• use custom templates from a path specified by user
• update its own self (phint update)

Autocompletion

The phint commands and options can be autocompleted if you use zsh shell with oh-my-zsh., _(*11)

Setting up auto complete:, _(*12)

mkdir -p ~/.oh-my-zsh/custom/plugins/ahccli && cd ~/.oh-my-zsh/custom/plugins/ahccli

[ -f ./ahccli.plugin.zsh ] || curl -sSLo ./ahccli.plugin.zsh https://raw.githubusercontent.com/adhocore/php-cli/master/ahccli.plugin.zsh

echo compdef _ahccli phint >> ./ahccli.plugin.zsh

chmod +x ./ahccli.plugin.zsh && source ./ahccli.plugin.zsh && cd -

Dont forget to add ahccli into plugins=(... ...) list in ~/.zshrc file., _(*13)

Usage

It can be used to quickly spin off new project containing all basic and default stuffs. The quick steps are as follows:, _(*14)

# See options/arguments
phint init --help

# OR (shortcut)
phint i -h

# Below command inits a brand new PHP project in `project-name` folder in current dir
# Missing arguments are interactively collected
phint init project-name

# You can also use config file (with json) to read option values from
phint init project-name --config phint.json

Commands

Each of the commands below should be used like so:, _(*15)

cd /path/to/project
phint <command> [--options] [args]

init

alias i, _(*16)

Create and Scaffold a bare new PHP project., _(*17)

Parameters:, _(*18)

Dont be intimidated by long list of parameters, you are not required to enter any of them as arguments as they are interactively collected when required., _(*19)

Also check config on how to create a reusable json config so you can use phint like a pro., _(*20)

Arguments:
  <project>  The project name without slashes

Options:
  [-b, --bin...]            Executable binaries
  [-c, --no-codecov]        Disable codecov
  [-C, --config]            JSON filepath to read config from
  [-d, --descr]             Project description
  [-D, --dev...]            Developer packages
  [-e, --email]             Vendor email
  [-f, --force]             Run even if the project exists
  [-G, --gh-template]       Use `.github/` as template path
                            By default uses `docs/`
  [-h, --help]              Show help
  [-w, --keywords...]       Project Keywords
  [-L, --license]           License (m: MIT, g: GNULGPL, a: Apache2, b: BSDSimple, i: ISC, w: WTFPL)
  [-n, --name]              Vendor full name
  [-N, --namespace]         Root namespace (use `/` separator)
  [-g, --package]           Packagist name (Without vendor handle)
  [-p, --path]              The project path (Auto resolved)
  [-P, --php]               Minimum PHP version
  [-R, --req...]            Required packages
  [-s, --no-scrutinizer]    Disable scrutinizer
  [-l, --no-styleci]        Disable StyleCI
  [-S, --sync]              Only create missing files
                            Use with caution, take backup if needed
  [-t, --no-travis]         Disable travis
  [-T, --type]              Project type
  [-u, --username]          Vendor handle/username
  [-z, --using]             Reference package
  [-y, --year]              License Year

Usage Examples:
  phint init <project> --force --descr "Awesome project" --name "YourName" --email you@domain.com
  phint init <project> --using laravel/lumen --namespace Project/Api --type project</comment>
  phint init <project> --php 7.0 --config /path/to/json --dev mockery/mockery --req adhocore/cli

Example config

Parameters sent via command args will have higher precedence than values from config file (-C --config)., _(*21)

What can you put in config? Anything but we suggest you put only known options (check $ phint init --help), _(*22)

{
  "type": "library",
  "namespace": "Ahc",
  "username": "adhocore",
  "name": "Jitendra Adhikari",
  "email": "jiten.adhikary@gmail.com",
  "php": "7.0",
  "codecov": false,
  "...": "..."
}

update

alias u, _(*23)

Update Phint to lastest version or rollback to earlier locally installed version., _(*24)

Parameters:, _(*25)

Options:
  [-h, --help]         Show help
  [-r, --rollback]     Rollback to earlier version

Usage Examples:
  phint update        Updates to latest version
  phint u             Also updates to latest version
  phint update -r     Rolls back to prev version
  phint u --rollback  Also rolls back to prev version

docs

alias d, _(*26)

Generate docs (.md) for all public classes and methods from their docblocks., _(*27)

Ideally you would run it on existing project or after you create/update src/ files., _(*28)

Parameters:, _(*29)

Options:
  [-a, --with-abstract]    Create docs for abstract/interface class
  [-h, --help]             Show help
  [-o, --output]           Output file (default README.md). For old project you should use something else
                           (OR mark region with  and  to inject docs)

Usage Examples:
  phint docs               If there is `<!-- DOCS START -->` and `<!-- DOCS END -->` region
                           Injects new doc in between them otherwise appends to bottom
  phint d -o docs/api.md   Writes to docs/api.md (Same rule applies regarding inject/append)

Sample docs

PHP code, _(*30)

namespace Abc;

/**
 * This is dummy class.
 *
 * It does nothing as of now.
 * Maybe you could fix it?
 */
class Dummy
{
    /**
     * Alpha beta.
     *
     * Example:
     *
     * <code>
     * $dummy = new Dummy;
     * $dummy->alpha('john', true);
     * // '...'
     * </code>
     *
     * @param string $name
     * @param bool   $flag
     *
     * @return string|null
     */
    public function alpha($name, $flag)
    {
        //
    }
}

Generated Markdown, _(*31)

## Dummy

```php
use Abc\Dummy;
\```

> This is dummy class.

It does nothing as of now.
Maybe you could fix it?

### alpha()

> Alpha beta.

```php
alpha(string $name, bool $flag): string|null
\```

Example:

```php
$dummy = new Dummy;
$dummy->alpha('john', true);
// '...'
\```

Preview, _(*32)

Dummy

use Ahc\Dummy;

This is dummy class., _(*33)

It does nothing as of now. Maybe you could fix it?, _(*34)

alpha()

Alpha beta., _(*35)

alpha(string $name, bool $flag): string|null

Example:, _(*36)

$dummy = new Dummy;
$dummy->alpha('john', true);
// '...'

test

alias t, _(*37)

Generate test files with proper classes and test methods analogous to their source counterparts. If a test class already exists, it is skipped. In future we may append test stubs for new methods., _(*38)

Ideally you would run it on existing project or after you create/update src/ files., _(*39)

Parameters:, _(*40)

Options:
  [-a, --with-abstract]    Create stub for abstract/interface class
  [-h, --help]             Show help
  [-n, --naming]           Test method naming format
                           (t: testMethod | m: test_method | i: it_tests_)
  [-p, --phpunit]          Base PHPUnit class to extend from
  [-s, --no-setup]         Dont add setup method
  [-t, --no-teardown]      Dont add teardown method

Usage Examples:
  phint test -n i        With `it_` naming
  phint t --no-teardown  Without `tearDown()`
  phint test -a          With stubs for abstract/interface

Sample test

Generated tests/Dummy.php for Abc\Dummy above:, _(*41)

<?php

namespace Abc\Test;

use Abc\Dummy;
use PHPUnit\Framework\TestCase as TestCase;

/**
 * Auto generated by `phint test`.
 */
class DummyTest extends TestCase
{
    /**
     * @var Dummy
     */
    protected $dummy;

    public function setUp()
    {
        parent::setUp();

        $this->dummy = new Dummy;
    }

    public function testAlpha()
    {
        $actual = $this->dummy->alpha();

        // $this->assertSame('', $actual);
    }
}

Templating

phint export --to ~/myphint, _(*42)

So you would like to have your own templates and customize phint to your taste!, _(*43)

First you need to create a directory root (of any name, eg: myphint) with structure that looks like:, _(*44)

myphint
├── CHANGELOG.md.twig
├── composer.json.twig
├── CONTRIBUTING.md.twig
├── docs
│   ├── docs.twig
│   ├── ISSUE_TEMPLATE.md.twig
│   └── PULL_REQUEST_TEMPLATE.md.twig
├── .editorconfig.twig
├── .env.example.twig
├── .gitignore.twig
├── LICENSE.twig
├── package.json.twig
├── phpunit.xml.dist.twig
├── README.md.twig
├── tests
│   ├── bootstrap.php.twig
│   └── test.twig
└── .travis.yml.twig

Note that you dont need to have all the files there in new directory just pick the ones you would like to customize and start hacking., _(*45)

Luckily you dont have to create these templates yourself, just run phint export --to ~/myphint!, _(*46)

Pro Tip You can actually introduce any new template as long as their extension is .twig. Such templates are only used by phint init command. Check Template variables., _(*47)

After you are done customizing these templates you can use them in each of the phint commands like so, _(*48)

phint init project --template ~/myphint
phint docs --template ~/myphint
phint test --template ~/myphint

The short option name for --template is -x., _(*49)

Template variables

Here's what parameters these templates would receive when run:, _(*50)

• docs/docs.twig: classes metadata and docs parameters
• tests/test.twig: class metadata and test parameters
• Everything else: init parameters

Metadata, _(*51)

• The docs and test commands read and use source files metadata.
• The docs.twig template recieves metadata collection of all classes at once.
• The test.twig template recieves metadata unit of one class at a time.

Class metadata

Example metadata for Abc\Dummy above:, _(*52)

[
  'namespace'   => 'Abc',
  'classFqcn'   => 'Abc\\Dummy',
  'classPath'   => '/home/user/projects/src/Dummy.php',
  'name'        => 'Dummy',
  'className'   => 'Dummy',
  'isTrait'     => false,
  'isAbstract'  => false,
  'isInterface' => false,
  'newable'     => true,
  'title'       => 'This is dummy class.',
  'texts'       => [
    'It does nothing as of now.',
    'Maybe you could fix it?',
  ],
  'methods' => [
    'alpha' => [
      'name'       => 'alpha',
      'inClass'    => 'Abc\\Dummy',
      'isStatic'   => false,
      'isFinal'    => false,
      'isPublic'   => true,
      'isAbstract' => false,
      'maybeMagic' => false,
      'title'      => 'Alpha beta.',
      'texts'      => [
        'Example:',
        '<code>',
        '$dummy = new Dummy;',
        '$dummy->alpha(\'john\', true);',
        '// \'...\'',
        '</code>',
      ],
      'return' => 'string|null',
      'params' => [
        'string $name',
        'bool $flag',
      ],
    ],
    // more methods ...
  ],
];

Todo

Including but not limited to:, _(*53)

• [x] README.md/Docs generator
• [x] Test files generator
• [x] Support user templates
• [ ] Test stubs for new methods

License

© 2017-2020, Jitendra Adhikari | MIT, _(*54)

Credits

This library is release managed by please., _(*55)