Download the PHP package styde/enlighten without Composer

Enlighten for Laravel

A seamless package to document your Laravel APIs.

There is no need to add endless docblocks to each API method, maintain dozens of readme files, or write extensive wikis to keep your APIs documented and in sync with your codebase!

Enlighten your Laravel applications with a beautiful documentation generated automatically from your test suites, by doing so, your documentation will always be updated with the current version of your app.

If you have already invested a lot of time developing and testing your API you don't need to spend the same amount of time documenting it, we'll do that for you, you deserve it!

Compatibility

Enlighten is compatible with Laravel 7.28 onwards and requires PHP from version 7.3.

You can be a part of this project:

• Join us on Discord
• Become a sponsor
• Become a contributor

Introducing Laravel Enlighten

After installing the component, run php artisan enlighten and that's it! You'll find the entire API documentation in the following URL: /enlighten/

Usage

After finishing the installation process, run your Laravel tests with the following command:

You can pass any option you'd normally pass to php artisan test including the --parallel option available in Laravel 8 onwards!

Now visit /enlighten/ to navigate the documentation.

Run php artisan enlighten:export to export the documentation as static files!

Demo project

Follow our 3min installation guide to see Enlighten in action in your own app (you don't need to modify your tests!)

Alternatively, install our demo project following the instructions in its README.

Installation

Installing Enlighten requires only 3 steps!

Step 1: Composer Require

Require the package with Composer as a dev dependency:

If you are NOT using the Laravel package auto-discovery feature, please add the following service-provider to config/app.php

Step 2: Install Enlighten

Run php artisan enlighten:install to install and setup Enlighten automatically, otherwise follow the instructions in the Manual Setup Section.

Step 3: Database Setup

Create and configure a database for Enlighten following the instructions below:

Enlighten needs its own database and database connection to record and preserve the documentation generated from your test suites.

If you use the following convention:

• A non-sqlite default database for your local enviroment (i.e. my_db)
• A non-sqlite database for your test enviroment with the _test or _tests suffix (i.e. my_db_tests)

Just add a new database using the same name of your default database with the _enlighten suffix, for example:

If you're not following the convention above, just add a new connection entry in config/database.php with the name enlighten and your custom configuration:

It's important to have a different connection and a different database for Enlighten in order to avoid having the info deleted or not persisted when using any of the database migration traits included by Laravel or if you run the tests using SQLite.

Use php artisan enlighten:migrate to run the package migrations.

You can also use: php artisan enlighten:migrate:fresh to refresh the migrations. Warning: this will also delete the auto generated documentation!

Manual Setup

If you didn't run php artisan enlighten:install or you received an error message, you can setup Enlighten manually following these instructions:

Publish the package assets (CSS, JavaScript) to the public folder using Artisan:

Optionally, you can publish the config file and views for more customization.

Third step: import the trait Styde\Enlighten\Tests\EnlightenSetup and call $this->setUpEnlighten() in the setUp method of your TestCase, for example:

Note: remember to include and use the trait Styde\Enlighten\Tests\EnlightenSetup.

Optional configuration

To "group" your tests-classes as "modules", you can use a regular expression to find all the classes that match with the given pattern or patterns:

You can add a "catch all" group at the end to include all those files that didn't match with any of the other patterns, otherwise Enlighten will do this automatically for you.

Excluding test-classes from the documentation

If you want to include all the test-classes and methods in your documentation, you can skip this step, otherwise, you can add the following key to the /config/enlighten.php file:

You can also ignore classes and methods adding the @enlighten {"ignore": true} annotation to any class OR method, for example:

If you'd like to do the opposite (include a class previously ignored via the configuration option) just add the @enlighten annotation to that class OR method:

Note: the annotations take precedence over the configuration option.

Customizing titles and descriptions

If you want to have more control on the titles of the classes and methods, or add descriptions to each group or example, you can add the following annotations in your test classes and methods:

Hiding sections from the view

You can hide entire UI sections from the view via config

Document your Internal API (Classes, Methods and Functions)

You can also create a code-snippet from your unit-tests by using the Enlighten::test() facade, this will allows you to add code-examples to your documentation.

Optionally, you can use the enlighten() helper instead of the Enlighten::test() facade.

Export the documentation as static HTML files

Since v0.4 you can use artisan to generate static files for your documentation:

You can select a custom export directory and base URL to use on the static files.

Customizing the intro page

To customize the content of your Dashboard page, you can add an ENLIGHTEN.md markdown file to the root path of your project. The content of this file will overwrite the default page provided by this package.

Community Links

English

• Enlighten Your APIs With Auto-Generated Documentation (LaravelNews.com)
• Composer 2.0, Enlightened APIs, and Mastering Nova (LaravelNews Podcast)
• Documentation in Laravel 8 with Enlighten (Oliver Earl)

  Spanish

• Genera la documentación de tus aplicaciones automáticamente con Laravel Enlighten (Styde.net)

  German

• Johannes Arndt: Laravel Enlighten - A seamless package to document your Laravel APIs (Laravel Meetup DACH)

Credits

• Duilio Palacios
• Jeff Ochoa
• All contributors

License

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