Generating PHP Documentation with Sami

Sami: A Powerful API Documentation Generator for PHP

Generating separate documentation for your PHP methods, classes, and functions is a best practice. This article introduces Sami, a robust API documentation generator that simplifies this process, improving readability and accessibility.

Key Features of Sami:

• Generates standalone documentation for PHP code, eliminating the need to navigate source code directly.
• Easy installation via PHAR archive or Composer.
• Highly configurable through a PHP configuration file, allowing customization of themes, titles, build directories, and caching.
• Supports custom themes and asset inclusion for a personalized look and feel.
• Integrates with Git version control, enabling documentation for multiple codebase versions.

Understanding DocBlocks:

DocBlocks are essential for Sami. They're multi-line comments placed above class, interface, method, or attribute definitions. Here's a Laravel example:

<code class="language-php">abstract class Manager
{
    /**
     * The application instance.
     *
     * @var \Illuminate\Foundation\Application
     */
    protected $app;

    /**
     * Create a new manager instance.
     *
     * @param \Illuminate\Foundation\Application $app
     * @return void
     */
    public function __construct($app)
    {
        $this->app = $app;
    }
}</code>

DocBlocks begin with /**, end with */, and each line within starts with *. Annotations like @param and @var provide additional information. phpDocumentor's annotation standards are widely supported.

Sami vs. Other Generators:

While other generators exist (e.g., phpDocumentor), Sami stands out due to its GitHub integration and Twig templating capabilities.

Installing Sami:

Choose one of these methods:

1. PHAR Archive: Download sami.phar and run php sami.phar.
2. Composer: Use composer require sami/sami:3.0.* to add Sami to your project. Then run php vendor/sami/sami/sami.php.

Generating Laravel Documentation (Example):

1. Clone the Laravel framework: git clone git@github.com:laravel/framework.git docs
2. Create a config/config.php file (see Configuration section below).
3. Run: php vendor/sami/sami/sami.php update config/config.php

Configuration (config/config.php):

This file returns a SamiSami instance:

<code class="language-php">$dir = __DIR__ . '/../docs';

$iterator = Symfony\Component\Finder\Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('build')
    ->exclude('tests')
    ->in($dir);

$options = [
    'theme'                => 'default',
    'title'                => 'Laravel API Documentation',
    'build_dir'            => __DIR__ . '/../build/laravel',
    'cache_dir'            => __DIR__ . '/../cache/laravel',
];

$sami = new Sami\Sami($iterator, $options);

return $sami;</code>

After running the update command, start a PHP server (php -S localhost:8000 -t build/) and access the documentation at http://localhost:8000/laravel/.

Git Versioning:

Sami excels at handling multiple Git versions. Add the versions option to your config:

<code class="language-php">abstract class Manager
{
    /**
     * The application instance.
     *
     * @var \Illuminate\Foundation\Application
     */
    protected $app;

    /**
     * Create a new manager instance.
     *
     * @param \Illuminate\Foundation\Application $app
     * @return void
     */
    public function __construct($app)
    {
        $this->app = $app;
    }
}</code>

Remember to include %version% in build_dir and cache_dir.

Creating Custom Themes:

Sami allows creating custom themes. Place a manifest.yml file in your theme directory (e.g., themes/mytheme/manifest.yml):

<code class="language-php">$dir = __DIR__ . '/../docs';

$iterator = Symfony\Component\Finder\Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('build')
    ->exclude('tests')
    ->in($dir);

$options = [
    'theme'                => 'default',
    'title'                => 'Laravel API Documentation',
    'build_dir'            => __DIR__ . '/../build/laravel',
    'cache_dir'            => __DIR__ . '/../cache/laravel',
];

$sami = new Sami\Sami($iterator, $options);

return $sami;</code>

Then, modify the base.twig template to include your CSS. Update your config file to use your custom theme: 'theme' => 'mytheme'. Run sami render config/config.php --force to regenerate the documentation.

Conclusion:

Sami offers a powerful and flexible solution for generating high-quality API documentation for your PHP projects. Its features, including Git versioning and custom theme support, make it a valuable tool for any PHP developer. The complete example is available on GitHub (link would be added here if a GitHub repo existed for this example).

The above is the detailed content of Generating PHP Documentation with Sami. For more information, please follow other related articles on the PHP Chinese website!