README

Artisense 📕

Laravel docs from the comfort of your terminal.

Motivation
How it works
Requirements
Getting started
Usage
- Versions
- Formatting
Changelog
Credits
License

Motivation

Artisense is meant to be a local-first offline copy of the Laravel documentation. Artisense is a set of artisan commands that allow you to locally store and search the laravel documentation from the comfort of your terminal.

If you're anything like me and living in the terminal, those precious seconds alt + tabing between code editor and browser to review the Laravel documentation really adds up (who has that kinda time?). Why not make docs accessible from the terminal?

How it works

At its core, artisense is a SQLite database that lives within your storage_path() underneath an artisense/ folder:

your-laravel-app/
  app/
  config/
  ...
  storage/
    artisense/
      artisense.sqlite // Where docs are stored
      docs-11.x/ // Documentation markdown files from 11.x
        artisan.md
        ...
      docs-12.x/ // Documentation markdown files from 12.x
        artisan.md
        ...
      docs-master.x/ // Documentation markdown files from master
        artisan.md
        ...
      zips/ // Zip archives of the documentation
        laravel-12.x.zip
        laravel-11.x.zip
        laravel-master.x.zip
        ...

Artisense uses SQLite to store documentation pulled from the Laravel documentation source. The documentation is downloaded as a zip file, extracted into a artisense/docs-{version}.x/ folder, then processed into sections to allow full-text search using SQLite's FTS5 extension. Since artisense is just a SQLite file, you may connect and query it like any other SQLite database.

Requirements

Laravel 12 or greater
PHP 8.4 or greater

Getting started

Install artisense with composer:

composer require --dev joeymckenzie/artisense

You may also publish the configuration file with:

php artisan vendor:publish --tag="artisense-config"

This will create the following config/artisense.php file:

return [

    /*
    |--------------------------------------------------------------------------
    | Documentation version
    |--------------------------------------------------------------------------
    |
    | Specifies the version of the documentation to use, with both numbered
    | versions and master available. By default, the most recent numbered
    | is used if no version is specified while attempting to download.
    |
    */

    'versions' => DocumentationVersion::VERSION_12,

    /*
    |--------------------------------------------------------------------------
    | Output Formatter
    |--------------------------------------------------------------------------
    |
    | Specifies the optional formatter that the output should use for markdown.
    | Markdown content will be returned from artisense and can be formatted
    | Using any formatting tools installed wherever artisense is running.
    |
    */

    'formatter' => BasicMarkdownFormatter::class,

    /*
    |--------------------------------------------------------------------------
    | Search Preference
    |--------------------------------------------------------------------------
    |
    | Specifies the search preferences to use when querying for documentation.
    | Ordered searches are used by default, returning results using ordered
    | phrase matching. You may choose your preference to adjust results.
    |
    */

    'search' => [
        'preference' => SearchPreference::ORDERED,
        'proximity' => 10,
    ],

    /*
    |--------------------------------------------------------------------------
    | Retain Artifacts
    |--------------------------------------------------------------------------
    |
    | Specifies the artificat retention policy artisense should use when processing
    | Laravel documentation. If set to true, documentation markdown files along
    | zip archives will be retained within the storage folder during install.
    |
    */

    'retain_artifacts' => true,

];

Artisense has a few tuning knobs within its configuration:

Version: specifies the version to run queries against, as multiple versions of the documentation may all be stored alongside one another
- Accepts either a single DocumentationVersion or an array of DocumentationVersions, e.g.

return [
    // Accepts a singe version
    'versions' => DocumentationVersion::VERSION_12,
    
    // You may also specify multiple versions
    'versions' => [
        DocumentationVersion::VERSION_11,
        DocumentationVersion::VERSION_12,
        DocumentationVersion::MASTER,
    ],
];

Formatter: specifies any custom formatting the markdown output should use when results are found
Search preference: SQLite full-text search preference, either ordered or unordered
Search proximity: relative distance between terms full-text search should consider when querying using an unordered preference

Usage

First, prepare artisense by running the install command:

php artisan artisense:install

You'll be prompted with a choice of versions to install:

🔧 Installing artisense...

 ┌ Which version of documentation would you like to install? ───┐
 │ › ◼ 12.x                                                     │
 │   ◻ 11.x                                                     │
 │   ◻ 10.x                                                     │
 │   ◻ master                                                   │
 └──────────────────────────────────────────────────────────────┘
  You can change the default version within the artisense.php config file.

Artisense uses Laravel Prompts, so any supported version of the documentation may be selected. Multiple versions of the documentation may be selected, where each will be processed and stored within the database allowing for querying across Laravel versions.

The install command will do a few things:

Download the Laravel markdown documentation files based on the configured version
Create a local SQLite database in your project within the storage folder under storage/artisense
Seed the database with the processed Laravel documentation

Usage

Artisense uses SQLite's full-text search extension FTS5 to query Laravel documentation. Once you've successfully installed a version of the documentation using artisense, you may use the artisense:search artisan command to search relevant sections:

php artisan artisense:search

 ┌ Enter a search term to find relevant information: ───────────┐
 │ Installing Reverb, handling Stripe webhooks, etc.            │
 └──────────────────────────────────────────────────────────────┘
  Use at least a few characters to get relevant results.

If any relevant documentation is found, matches will be displayed in the terminal:

 ┌ Enter a search term to find relevant information: ───────────────┐
 │ pennant                                                          │
 ├──────────────────────────────────────────────────────────────────┤
 │   2407 - 12.x - Laravel Pennant - Configuration                ┃ │
 │   2406 - 12.x - Laravel Pennant - Installation                 │ │
 │   2433 - 12.x - Laravel Pennant - Store Configuration          │ │
 └──────────────────────────────────────────────────────────────────┘
  Use at least a few characters to get relevant results.

and if you select an entry:

Laravel Pennant - Defining Features Externally - 12.x

Defining Features Externally

If your driver is a wrapper around a third-party feature flag platform, you will likely define features on the platform rather than using Pennant's Feature::define method. If that is the case, your custom driver should also implement the Laravel\Pennant\Contracts\DefinesFeaturesExternally interface:
<?php

namespace App\Extensions;

use Laravel\Pennant\Contracts\Driver;
use Laravel\Pennant\Contracts\DefinesFeaturesExternally;

class FeatureFlagServiceDriver implements Driver, DefinesFeaturesExternally
{
    /**
     * Get the features defined for the given scope.
     */
    public function definedFeaturesForScope(mixed $scope): array {}

    /* ... */
}
The definedFeaturesForScope method should return a list of feature names defined for the provided scope.

Learn more: https://laravel.com/docs/12.x/pennant#defining-features-externally

By default, artisense returns the raw markdown from the content that was used to find the relevant section. A link to the section within the documentation will also included.

Versions

Within your artisense.php configuration file, you may specify one or more versions of Laravel documentation to use when processes, storing, and searching documentations with artisense commands:

return [

    // Other configurations...
    
    // Specify a version using the `DocumentationVersion` enum
    'versions' => DocumentationVersion::MASTER
    
    // Specify versions using the `DocumentationVersion` enum
    'versions' => [
        DocumentationVersion::VERSION_12,
        DocumentationVersion::VERSION_11,
        DocumentationVersion::MASTER,
    ]
    
]

When installing documentation, artisense will default to using the versions specified within your configuration file. When using the search commands, artisense will also use whichever versions are specified within your configuration to filter on search results.

For example, if you have versions 12.x, 11.x, and master installed, all search results will be returned:

php artisan artisense:search

 ┌ Enter a search term to find relevant information: ─────────────────┐
 │ validation                                                         │
 ├────────────────────────────────────────────────────────────────────┤
 │   7494 - 11.x - Validation - Accessing Additional Data           ┃ │
 │   11237 - master - Validation - Accessing Additional Data        │ │
 │   3718 - 12.x - Validation - Accessing Additional Data           │ │
 └────────────────────────────────────────────────────────────────────┘
  Use at least a few characters to get relevant results.

Formatting

You may customize the output of the artisense:search command through the use of an output formatter. The search command will output the raw markdown processed from the identified documentation section, though if an output formatter is specified within configuration, it will use that format the output.

By default, artisense includes two simple output formatter:

a basic markdown formatter
a glow-based output formatter (requires glow to be installed)

You may specify a custom formatter within your artisense.php configuration:

return [

    // Other configuration...

    'formatter' => \App\Support\Formatters\CustomMarkdownFormatter::class,

];

You may then implement the OutputFormatterContract to format the markdown:

<?php

declare(strict_types=1);

namespace App\Support\Formatters;

use Artisense\Contracts\OutputFormatterContract;

final class TestOutputFormatter implements OutputFormatterContract
{
    public function format(string $markdown): string
    {
        return "FORMATTED: $markdown";
    }
}

joeymckenzie / artisense

Maintainers

Details

README

Artisense 📕

Table of Contents

Motivation

How it works

Requirements

Getting started

Usage

Usage

Defining Features Externally

Versions

Formatting

Changelog

Credits

License