README

A small Laravel package for formatting SQL statements and files inside your Blade templates.

This package uses doctrine/sql-formatter to indent and add line breaks in addition to syntax highlighting.

Installation

Requires PHP 8.0+ and Laravel 9+

You can install the package via composer:

composer require sebdesign/blade-sql-formatter

You can publish the config file with:

php artisan vendor:publish --tag="blade-sql-formatter-config"

This is the contents of the published config file:

<?php

use Doctrine\SqlFormatter\HtmlHighlighter;

return [
    'highlighter' => HtmlHighlighter::class,

    'html_attributes' => [
        HtmlHighlighter::HIGHLIGHT_QUOTE => 'style="color: blue;"',
        HtmlHighlighter::HIGHLIGHT_BACKTICK_QUOTE => 'style="color: purple;"',
        HtmlHighlighter::HIGHLIGHT_RESERVED => 'style="font-weight:bold;"',
        HtmlHighlighter::HIGHLIGHT_BOUNDARY => '',
        HtmlHighlighter::HIGHLIGHT_NUMBER => 'style="color: green;"',
        HtmlHighlighter::HIGHLIGHT_WORD => 'style="color: #333;"',
        HtmlHighlighter::HIGHLIGHT_ERROR => 'style="background-color: red;"',
        HtmlHighlighter::HIGHLIGHT_COMMENT => 'style="color: #aaa;"',
        HtmlHighlighter::HIGHLIGHT_VARIABLE => 'style="color: orange;"',
        HtmlHighlighter::HIGHLIGHT_PRE => 'style="color: black; background-color: white;"',
    ],

    'use_pre' => true,

    'indent_string' => '  ',
];

Feel free to customize the style of each token. You can use inline styles or CSS classes, even Tailwind CSS. Check out the demo on Tailwind Play.

Usage

Input:

select * from `users` where `id` = 1 limit 1

Output:

select
  *
from
  `users`
where
  `id` = 1
limit
  1

View component

<!-- Formatting and syntax highlighting -->
<x-sql>
    select * from `users` where `id` = 1 limit 1
</x-sql>

<!-- Component attributes -->
<x-sql class="bg-gray-100 rounded-xl">
    select * from `users` where `id` = 1 limit 1
</x-sql>

<!-- Syntax highlighting only -->
<x-sql :format="false">
    select * from `users` where `id` = 1 limit 1
</x-sql>

<!-- Formatting only -->
<x-sql :highlight="false">
    select * from `users` where `id` = 1 limit 1
</x-sql>

HTML Entity Encoding

If you use Blade's {{ }} echo statements inside the <x-sql> component, they will be sent through htmlspecialchars automatically. If your SQL statement contains single ' or double " quotes, they will be double-encoded.

For example:

@php($sql = "select * from `users` where `email` = 'info@example.com'")

<x-sql>{{ $sql }}</x-sql>

Will output:

select
  *
from
  `users`
where
  `email` = & #039;info@example.com&#039;

In order to address this, you can use raw echo statements {!! !!} on your own responsibility.

Learn more about displaying unescaped data.

For example:

@php($sql = "select * from `users` where `email` = 'info@example.com'")

<x-sql>{!! $sql !!}</x-sql>

Will output:

select
  *
from
  `users`
where
  `email` = 'info@example.com'

Blade directive

<!-- Format the SQL statement string -->
@sql('select * from `users` where `id` = 1 limit 1')

<!-- Format the SQL statement block -->
@sql
    select * from `users` where `id` = 1 limit 1
@endsql

Rendering and including views

You can render and include SQL files like Blade files inside your controllers and your views. The SQL files will be compiled as formatted and highlighted HTML files, and will be cached in the compiled view path, e.g.: storage/framework/views.

If you don't want to store you SQL files in the resources/views directory, you can load them from another location, by adding the path in the paths key of your config/view.php file.

The following example will use the database/queries directory to find SQL files:

return [
    'paths' => [
        resource_path('views'),
        database_path('queries'),
    ],
];

If you prefer using a namespace to separate your Blade files from your SQL files, you can add one in the boot method of a service provider.

The following example will use the database/queries directory to find SQL files with the sql:: namespace:

In this case you don't need to add the path to config/view.php.

public function boot()
{
    $this->loadViewsFrom(database_path('queries'), 'sql');
}

Render database/queries/users/select-first-user.sql from a controller.

public function show()
{
    return view('sql::users.select-first-user');
}

Include database/queries/users/select-first-user.sql within a Blade view.

@include('sql::users.select-first-user')

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

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

Credits

License

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

sebdesign / blade-sql-formatter

Maintainers

Details