vicgutt/laravel-inspect-db

Inspect and retrieve information about a given database

v0.1.3 2023-03-16 18:10 UTC

Requires

• php: ^8.1
• doctrine/dbal: ^3.4
• illuminate/contracts: ^10.0
• spatie/laravel-package-tools: ^1.9.2
• vicgutt/php-enhanced-enum: ^0.1.0

Requires (Dev)

• laravel/pint: ^1.0
• nunomaduro/collision: ^6.0
• nunomaduro/larastan: ^2.0.1
• orchestra/testbench: ^8.0
• pestphp/pest: ^1.21
• pestphp/pest-plugin-laravel: ^1.1
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• phpunit/phpunit: ^9.5
• spatie/invade: ^1.1

MIT

• Victor GUTT

• database
• laravel

README

This package allows you to inspect and retrieve information about your databases. This package has been tested against Sqlite, MySQL and PostgreSQL although others might work as well, if not, let's discuss it.

Here's a quick example:

use VicGutt\InspectDb\Inspect;

// On a default Laravel "users" table using the "mysql" connection, running:
Inspect::table($name = 'users', $connectionOrSchemaManagerOrNull = 'mysql')->toArray();

// would return the following:
[
    'name' => 'users',
    'engine' => 'InnoDB',
    'collation' => 'utf8mb4_unicode_ci',
    'charset' => 'utf8mb4',
    'autoincrement' => 1,
    'comment' => '',
    'primaryKey' => [
        'name' => 'PRIMARY',
        'primary' => true,
        'unique' => true,
        // ...
    ],
    'columns' => [
        'id' => [/* ... */],
        'name' => [/* ... */],
        'email' => [/* ... */],
        // ...
    ],
    'indexes' => [/* ... */],
    'foreignKeys' => [],
]

Installation

You can install the package via composer:

composer require vicgutt/laravel-inspect-db

You can publish the config file with:

php artisan vendor:publish --tag="laravel-inspect-db-config"

You can check out what the contents of the published config file will be here: config/inspect-db.php

Inspect

The VicGutt\InspectDb\Inspect class is the main entry point of the package. It allows you to retrieve information about tables, a table's columns, it's indexes and foreign keys.

Retrieving the tables of a given database connection

use VicGutt\InspectDb\Inspect;

// returns an instance of `VicGutt\InspectDb\Collections\Entities\TableCollection`
Inspect::tables();

Here, as no database connection was specified, the default configured database connection will be used.

Retrieving a particular table for a given database connection

use VicGutt\InspectDb\Inspect;

// returns an instance of `VicGutt\InspectDb\Entities\Table`
Inspect::table('users');

Here, as no database connection was specified as second argument, the default configured database connection will be used.

Retrieving the columns of a particular table for a given database connection

use VicGutt\InspectDb\Inspect;

// returns an instance of `VicGutt\InspectDb\Collections\Entities\ColumnCollection`
Inspect::columns('users');

Here, as no database connection was specified as second argument, the default configured database connection will be used.

Retrieving the indexes of a particular table for a given database connection

use VicGutt\InspectDb\Inspect;

// returns an instance of `VicGutt\InspectDb\Collections\Entities\IndexCollection`
Inspect::indexes('users');

Here, as no database connection was specified as second argument, the default configured database connection will be used.

Retrieving the foreign keys of a particular table for a given database connection

use VicGutt\InspectDb\Inspect;

// returns an instance of `VicGutt\InspectDb\Collections\Entities\ForeignKeyCollection`
Inspect::foreignKeys('users');

Here, as no database connection was specified as second argument, the default configured database connection will be used.

Retrieving a particular column of a particular table for a given database connection

use VicGutt\InspectDb\Inspect;

// returns an instance of `VicGutt\InspectDb\Entities\Column` or null
Inspect::column('id', 'users');

Here, as no database connection was specified as third argument, the default configured database connection will be used.

Retrieving a particular index of a particular table for a given database connection

use VicGutt\InspectDb\Inspect;

// returns an instance of `VicGutt\InspectDb\Entities\Index` or null
Inspect::index('PRIMARY', 'users');

Here, as no database connection was specified as third argument, the default configured database connection will be used.

Retrieving a particular foreign key of a particular table for a given database connection

use VicGutt\InspectDb\Inspect;

// returns an instance of `VicGutt\InspectDb\Entities\ForeignKey` or null
Inspect::foreignKey('posts_user_id_foreign', 'posts');

Here, as no database connection was specified as third argument, the default configured database connection will be used.

Collections

The collections provided by this package all extend the abstract VicGutt\InspectDb\Collections\Entities\EntityCollection class which itself extends from the default Laravel collection (Illuminate\Support\Collection).

The available collections are:

• VicGutt\InspectDb\Collections\Entities\TableCollection
• VicGutt\InspectDb\Collections\Entities\ColumnCollection
• VicGutt\InspectDb\Collections\Entities\IndexCollection
• VicGutt\InspectDb\Collections\Entities\ForeignKeyCollection

The above collections differ slightly from the default Laravel collection and behavior you might be used to. That is, our collections internal items can only ever be an array of the entities they represent. As an example, the TableCollection items can only ever be an array of Tables.

In usage, this translates to type errors being thrown when some collection methods are used:

/**
 * The following will throw a `TypeError` with a message specifying the "$item" given
 * is a string rather than instances of `Doctrine\DBAL\Schema\Table` or `VicGutt\InspectDb\Entities\Table`.
 */
Inspect::tables()->map(fn (Table $table): string => $table->name);
Inspect::tables()->pluck('name');

The solution to this is to convert our Collection into a default Laravel collection prior to calling methods which returns new instances of the current collection but with mutated items:

/**
 * Now, all is well.
 */
Inspect::tables()->toBase()->map(fn (Table $table): string => $table->name);
Inspect::tables()->toBase()->pluck('name');

This behavior, although admittedly surprising, helps guarantee a collection of Xs only ever actually contains Xs.

Entities

Entities are meant to represent units present in a given database.

The available entities are:

• VicGutt\InspectDb\Entities\Table
• VicGutt\InspectDb\Entities\Column
• VicGutt\InspectDb\Entities\Index
• VicGutt\InspectDb\Entities\ForeignKey

Click on any of the listed entities above to learn more about the exposed properties and methods.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

If you're interested in contributing to the project, please read our contributing docs before submitting a pull request.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Victor GUTT
• All Contributors

License

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