{"id":13563571,"url":"https://github.com/StydeNet/enlighten","last_synced_at":"2025-04-03T20:31:11.686Z","repository":{"id":42622504,"uuid":"297606633","full_name":"StydeNet/enlighten","owner":"StydeNet","description":"Enlighten your APIs with auto-generated documentation","archived":false,"fork":false,"pushed_at":"2024-05-06T17:34:06.000Z","size":10472,"stargazers_count":574,"open_issues_count":13,"forks_count":32,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-03-07T00:36:14.716Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StydeNet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["sileence"],"patreon":"duiliopalacios","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-09-22T09:54:11.000Z","updated_at":"2025-02-28T08:05:05.000Z","dependencies_parsed_at":"2024-01-14T03:47:12.175Z","dependency_job_id":"439a6d07-ed4b-4082-8318-9f90f723dab8","html_url":"https://github.com/StydeNet/enlighten","commit_stats":{"total_commits":605,"total_committers":18,"mean_commits":"33.611111111111114","dds":"0.39669421487603307","last_synced_commit":"69aeda8ebd29deebb5ebe769a375e9a4cc83cfd0"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StydeNet%2Fenlighten","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StydeNet%2Fenlighten/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StydeNet%2Fenlighten/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StydeNet%2Fenlighten/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StydeNet","download_url":"https://codeload.github.com/StydeNet/enlighten/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247074519,"owners_count":20879263,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:01:20.776Z","updated_at":"2025-04-03T20:31:10.496Z","avatar_url":"https://github.com/StydeNet.png","language":"PHP","readme":"# Enlighten for Laravel\n\n![](https://github.com/StydeNet/enlighten/workflows/run-tests/badge.svg) [![Latest Stable Version](https://poser.pugx.org/styde/enlighten/v)](//packagist.org/packages/styde/enlighten) [![Total Downloads](https://poser.pugx.org/styde/enlighten/downloads)](//packagist.org/packages/styde/enlighten) [![License](https://poser.pugx.org/styde/enlighten/license)](//packagist.org/packages/styde/enlighten)\n\nA seamless package to document your Laravel APIs.\n\nThere 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!\n\nEnlighten 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.\n\nIf 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!\n\n## Compatibility\n\nEnlighten is compatible with Laravel 7.28 onwards and requires PHP from version 7.3.\n \n## You can be a part of this project:\n- [Join us on Discord](https://discord.gg/JyfxmPM)\n- [Become a sponsor](https://github.com/sponsors/sileence)\n- [Become a contributor](https://github.com/StydeNet/enlighten/blob/main/CONTRIBUTING.md)\n\n## Introducing Laravel Enlighten\n\n![Enlighten preview](./preview.png \"Enlighten Dashboard preview\")\n\nAfter installing the component, run `php artisan enlighten` and that's it! You'll find the entire API documentation in the following URL: `/enlighten/`\n\n## Usage\nAfter finishing the installation process, run your Laravel tests with the following command:\n\n```bash\nphp artisan enlighten\n```\n\nYou can pass any option you'd normally pass to `php artisan test` including the `--parallel` option available in Laravel 8 onwards!\n\nNow visit `/enlighten/` to navigate the documentation.\n\nRun `php artisan enlighten:export` to export the documentation as static files!\n\n## Demo project\n\nFollow our 3min installation guide to see Enlighten in action in your own app (you don't need to modify your tests!)\n\nAlternatively, install our [demo project](https://github.com/StydeNet/curso-de-laravel-desde-cero/tree/enlighten) following the instructions in its README.\n\n## Installation\n\nInstalling Enlighten requires only 3 steps!\n\n## Step 1: Composer Require\n\nRequire the package with Composer as a **dev** dependency:\n\n```bash\ncomposer require styde/enlighten --dev\n```\n\nIf you are NOT using the Laravel package auto-discovery feature, please add the following service-provider to `config/app.php`\n\n```php\n[\n    'providers' =\u003e [\n        // ...\n        Styde\\Enlighten\\Providers\\EnlightenServiceProvider::class,\n    ]\n];\n```\n\n# Step 2: Install Enlighten\n\nRun `php artisan enlighten:install` to install and setup Enlighten automatically, otherwise follow the instructions in the [Manual Setup Section](#manual-setup).\n\n## Step 3: Database Setup\n\nCreate and configure a database for Enlighten following the instructions below:\n\n`Enlighten` needs its own database and database connection to record and preserve the documentation generated from your test suites.\n\nIf you use the following convention: \n\n* A non-sqlite default database for your local enviroment (i.e. `my_db`)\n* A non-sqlite database for your test enviroment with the `_test` or `_tests` suffix (i.e. `my_db_tests`) \n\nJust add a new database using the same name of your default database with the `_enlighten` suffix, for example:\n\n```text\n# .env\n# If your local database is:\nDB_NAME=my_default_database\n#\n# phpunit.xml\n# And your test database is:\n# \u003cenv name=\"DB_DATABASE\" value=\"my_default_database_tests\"/\u003e\n#\n# Then Enlighten will use a third database automatically:\n# my_default_database_enlighten\n```\n\nIf 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:\n\n```\n   'enlighten' =\u003e [\n       'driver' =\u003e 'mysql',\n       'host' =\u003e env('DB_HOST', '127.0.0.1'),\n       'port' =\u003e env('DB_PORT', '3306'),\n       'database' =\u003e 'my_enlighten_database',\n       // ...\n    ],\n```\n\n\u003e 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\n\u003e using any of the database migration traits included by Laravel or if you run the tests using SQLite.\n\nUse `php artisan enlighten:migrate` to run the package migrations.\n\nYou can also use: `php artisan enlighten:migrate:fresh` to refresh the migrations. Warning: this will also delete the auto generated documentation!\n\n## Manual Setup\n\nIf you didn't run `php artisan enlighten:install` or you received an error message, you can setup Enlighten manually following these instructions:\n\nPublish the package assets (CSS, JavaScript) to the public folder using Artisan:\n\n```bash\nphp artisan vendor:publish --tag=enlighten-build\n```\n\nOptionally, you can publish the config file and views for more customization.\n\n```bash\nphp artisan vendor:publish --tag=enlighten-config\nphp artisan vendor:publish --tag=enlighten-views\n```\n\nThird step: import the trait `Styde\\Enlighten\\Tests\\EnlightenSetup` and call `$this-\u003esetUpEnlighten()` in the `setUp` method of your `TestCase`, for example:\n\n```php\n\u003c?php\n\nnamespace Tests;\n\nuse Styde\\Enlighten\\Tests\\EnlightenSetup;\n\nclass TestCase extends \\Tests\\TestCase\n{\n    use EnlightenSetup;\n\n    protected function setUp(): void\n    {\n        parent::setUp();\n\n        $this-\u003esetUpEnlighten();\n    }\n}\n```\n\n*Note:* remember to include and use the trait `Styde\\Enlighten\\Tests\\EnlightenSetup`.\n\n## Optional configuration\nTo \"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:\n\n```php\n// config/enlighten.php\n[\n    'modules' =\u003e [\n        [\n            'name' =\u003e 'Users',\n            'pattern' =\u003e ['*Users*']\n        ],\n        [\n            'name' =\u003e 'Projects',\n            'pattern' =\u003e ['*Projects*', '*Project*']\n        ],\n        [\n            'name' =\u003e 'Other Modules',\n            'pattern' =\u003e ['*'],\n        ],\n    ]\n];\n```\n\n\u003e 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.\n\n## Excluding test-classes from the documentation\nIf 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:\n\n```php\n[\n    'tests' =\u003e [\n        // Add expressions to ignore test class names and test method names.\n        // i.e. Tests\\Unit\\* ignores all tests in the Tests\\Unit\\ suite,\n        // validates_* ignores all tests that start with validates_.\n        'ignore' =\u003e [\n            'method_that_will_be_ignored',\n        ],\n    ],\n];\n```\n\nYou can also ignore classes and methods adding the `@enlighten {\"ignore\": true}` annotation to any class OR method, for example:\n\n```php\n/**\n * @enlighten {\"ignore\": true}\n */\nclass IgnoreClassWithAnnotationTest extends TestCase\n{\n    use RefreshDatabase;\n\n    /**\n     * @test\n     * @enlighten {\"ignore\": true}\n     */\n    function does_not_export_test_methods_with_the_enlighten_ignore_annotation()\n    {\n        $this-\u003eassertExampleIsNotCreated();\n    }\n}\n```\n\nIf 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:\n\n```php\n/**\n * @enlighten\n */\nclass IncludeMethodWithAnnotationTest extends TestCase\n{\n    /**\n     * @test\n     * @enlighten\n     */\n    function export_test_method_with_the_enlighten_annotation_even_if_its_ignored_in_the_config()\n    {\n        $this-\u003eassertExampleIsCreated();\n    }\n}\n```\n\n**Note:** the annotations take precedence over the configuration option.\n\n## Customizing titles and descriptions\nIf 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:\n\n```php\n/**\n * @title User Module\n *\n * or if you prefer:\n *\n * @testdox User Module\n *\n *  and you can also use:\n *\n * @description Manage all the user-related petitions.\n **/\nclass UsersTest extends TestCase {\n\n    /**\n     *\n     * @testdox Create Users\n     *\n     * @description Register a new user via POST request. API credentials must be provided.\n     **/\n    public function testRegisterNewUsers()\n    {\n        $this-\u003eassertTrue(true);\n    }\n}\n```\n\n## Hiding sections from the view\n\nYou can hide entire UI sections from the view via config\n\n```php\n// config/enlighten.php\nreturn [\n    // Add values to this array if you want to hide certain sections from your views.\n    // For valid sections see \\Styde\\Enlighten\\Section\n    'hide' =\u003e [\n        //\n    ],\n];\n```\n\n## Document your Internal API (Classes, Methods and Functions)\n\nYou 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.\n\n```php\n\nuse Styde\\Enlighten\\Facades\\Settings;\n\nclass CalcTest extends TestCase\n{\n    /**\n     * @test \n     * @testdox Sum two numbers\n     * @description Use the Calc `sum` static method to sum two numbers.\n    **/\n    public function can_sum_two_numbers()\n    {\n        $result = Settings::test(function () {\n            $a = 1;\n            $b = 2;\n            return Calc::sum($a, $b);\n        });\n          \n        $this-\u003eassertSame(3, $result);\n    }\n}\n```\n\nOptionally, you can use the `enlighten()` helper instead of the `Enlighten::test()` facade.\n\n## Export the documentation as static HTML files\n\nSince `v0.4` you can use artisan to generate static files for your documentation:\n\n```bash\nphp artisan enlighten:export\n```\n\nYou can select a custom export directory and base URL to use on the static files.\n\n## Customizing the intro page\n\nTo customize the content of your Dashboard page, you can add an `ENLIGHTEN.md` markdown file to the root path of your project.\nThe content of this file will overwrite the default page provided by this package.\n\n## Community Links\n### English\n- [Enlighten Your APIs With Auto-Generated Documentation (LaravelNews.com)](https://laravel-news.com/enlighten-laravel-apis)\n- [Composer 2.0, Enlightened APIs, and Mastering Nova (LaravelNews Podcast)](https://laravel-news.com/composer-2-0-enlightened-apis-and-mastering-nova)\n- [Documentation in Laravel 8 with Enlighten (Oliver Earl)](https://blog.oliverearl.co.uk/documentation-in-laravel-8-with-enlighten)\n### Spanish\n- [Genera la documentación de tus aplicaciones automáticamente con Laravel Enlighten (Styde.net)](https://styde.net/laravel-enlighten/)\n### German\n- [Johannes Arndt: Laravel Enlighten - A seamless package to document your Laravel APIs (Laravel Meetup DACH)](https://youtu.be/-LEztUG-E9g?t=336)\n\n## Credits\n- [Duilio Palacios](https://twitter.com/sileence)\n- [Jeff Ochoa](https://twitter.com/jeffer_8a)\n- [All contributors](https://github.com/StydeNet/enlighten/graphs/contributors)\n\n## License\nThe MIT License (MIT). Please see [License](https://github.com/styde/enlighten/blob/master/LICENSE.md) File for more information.\n","funding_links":["https://github.com/sponsors/sileence","https://patreon.com/duiliopalacios"],"categories":["PHP"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStydeNet%2Fenlighten","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStydeNet%2Fenlighten","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStydeNet%2Fenlighten/lists"}