Skip to content

Commit bd0d7a6

Browse files
tpetrytpetry
committed
initial release
0 parents  commit bd0d7a6

30 files changed

+1224
-0
lines changed

‎.editorconfig

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
indent_size = 4
7+
indent_style = space
8+
insert_final_newline = true
9+
trim_trailing_whitespace = true
10+
11+
[*.md]
12+
trim_trailing_whitespace = false
13+
14+
[*.{yml,yaml}]
15+
indent_size = 2

‎.gitattributes

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Path-based git attributes
2+
# https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html
3+
4+
# Ignore all test and documentation with "export-ignore".
5+
/.github export-ignore
6+
/.gitattributes export-ignore
7+
/.gitignore export-ignore
8+
/phpunit.xml.dist export-ignore
9+
/art export-ignore
10+
/docs export-ignore
11+
/tests export-ignore
12+
/.editorconfig export-ignore
13+
/.php_cs.dist.php export-ignore
14+
/psalm.xml export-ignore
15+
/psalm.xml.dist export-ignore
16+
/testbench.yaml export-ignore
17+
/UPGRADING.md export-ignore
18+
/phpstan.neon.dist export-ignore
19+
/phpstan-baseline.neon export-ignore

‎.github/ISSUE_TEMPLATE/bug.yml

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: Bug Report
2+
description: Report an Issue or Bug with the Package
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
We're sorry to hear you have a problem. Can you help us solve it by providing the following details.
10+
- type: textarea
11+
id: what-happened
12+
attributes:
13+
label: What happened?
14+
description: What did you expect to happen?
15+
placeholder: I cannot currently do X thing because when I do, it breaks X thing.
16+
validations:
17+
required: true
18+
- type: textarea
19+
id: how-to-reproduce
20+
attributes:
21+
label: How to reproduce the bug
22+
description: How did this occur, please add any config values used and provide a set of reliable steps if possible.
23+
placeholder: When I do X I see Y.
24+
validations:
25+
required: true
26+
- type: input
27+
id: package-version
28+
attributes:
29+
label: Package Version
30+
description: What version of our Package are you running? Please be as specific as possible
31+
placeholder: 2.0.0
32+
validations:
33+
required: true
34+
- type: input
35+
id: php-version
36+
attributes:
37+
label: PHP Version
38+
description: What version of PHP are you running? Please be as specific as possible
39+
placeholder: 8.2.0
40+
validations:
41+
required: true
42+
- type: input
43+
id: laravel-version
44+
attributes:
45+
label: Laravel Version
46+
description: What version of Laravel are you running? Please be as specific as possible
47+
placeholder: 9.0.0
48+
validations:
49+
required: true
50+
- type: dropdown
51+
id: operating-systems
52+
attributes:
53+
label: Which operating systems does with happen with?
54+
description: You may select more than one.
55+
multiple: true
56+
options:
57+
- macOS
58+
- Windows
59+
- Linux
60+
- type: textarea
61+
id: notes
62+
attributes:
63+
label: Notes
64+
description: Use this field to provide any other notes that you feel might be relevant to the issue.
65+
validations:
66+
required: false

‎.github/ISSUE_TEMPLATE/config.yml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Ask a question
4+
url: https://github.com/tpetry/laravel-mysql-explain/discussions/new?category=q-a
5+
about: Ask the community for help
6+
- name: Request a feature
7+
url: https://github.com/tpetry/laravel-mysql-explain/discussions/new?category=ideas
8+
about: Share ideas for new features
9+
- name: Report a security issue
10+
url: https://github.com/tpetry/laravel-mysql-explain/security/policy
11+
about: Learn how to notify us for sensitive bugs

‎.github/workflows/code-style.yml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Code Style
2+
3+
on: [push, pull_request]
4+
5+
permissions:
6+
contents: write
7+
8+
jobs:
9+
php-code-styling:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v3
15+
16+
- name: Fix PHP code style issues
17+
uses: aglipanci/[email protected]
18+
19+
- name: Commit changes
20+
uses: stefanzweifel/git-auto-commit-action@v4
21+
with:
22+
commit_message: Fix styling

‎.github/workflows/static-analysis.yml

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Static Analysis
2+
3+
on: [push, pull_request]
4+
5+
jobs:
6+
phpstan:
7+
name: phpstan
8+
runs-on: ubuntu-latest
9+
steps:
10+
- name: Checkout code
11+
uses: actions/checkout@v3
12+
13+
- name: Setup PHP
14+
uses: shivammathur/setup-php@v2
15+
with:
16+
php-version: '8.2'
17+
coverage: none
18+
19+
- name: Install composer dependencies
20+
uses: ramsey/composer-install@v2
21+
22+
- name: Run PHPStan
23+
run: ./vendor/bin/phpstan --error-format=github

‎.github/workflows/unit-tests.yml

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Unit Tests
2+
3+
on: [push, pull_request]
4+
5+
jobs:
6+
test:
7+
runs-on: ubuntu-latest
8+
strategy:
9+
fail-fast: false
10+
matrix:
11+
php: [8.0, 8.1, 8.2]
12+
laravel: [6.*, 7.*, 8.*, 9.*, 10.*]
13+
stability: [prefer-lowest, prefer-stable]
14+
exclude:
15+
# These combinations should work, but there is a problem when testing...
16+
- laravel: 8.*
17+
php: 8.1
18+
- laravel: 8.*
19+
php: 8.2
20+
# Laravel 10.x only supports PHP ^8.1
21+
- laravel: 10.*
22+
php: 8.0
23+
# Laravel 7.x only supports PHP 7.2-8.0
24+
- laravel: 7.*
25+
php: 8.1
26+
- laravel: 7.*
27+
php: 8.2
28+
# Laravel 6.x only supports PHP 7.2-8.0
29+
- laravel: 6.*
30+
php: 8.1
31+
- laravel: 6.*
32+
php: 8.2
33+
34+
name: L${{ matrix.laravel }} - P${{ matrix.php }} - ${{ matrix.color }} - ${{ matrix.stability }}
35+
36+
steps:
37+
- name: Checkout code
38+
uses: actions/checkout@v3
39+
40+
- name: Setup PHP
41+
uses: shivammathur/setup-php@v2
42+
with:
43+
php-version: ${{ matrix.php }}
44+
45+
- name: Setup problem matchers
46+
run: |
47+
echo "::add-matcher::${{ runner.tool_cache }}/php.json"
48+
echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
49+
50+
- name: Install dependencies
51+
run: |
52+
composer require "laravel/framework:${{ matrix.laravel }}" --no-interaction --no-update
53+
composer update --${{ matrix.stability }} --prefer-dist --no-interaction
54+
55+
- name: List Installed Dependencies
56+
run: composer show
57+
58+
- name: Execute tests
59+
run: vendor/bin/phpunit

‎.gitignore

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.idea
2+
.phpunit.cache
3+
build
4+
composer.lock
5+
coverage
6+
docs
7+
phpunit.xml
8+
phpstan.neon
9+
testbench.yaml
10+
vendor
11+
node_modules

‎CHANGELOG.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2023-06-12
9+
### Added
10+
* `explainForHumans()` for query builders
11+
* `dumpExplainForHumans()` for query builders
12+
* `ddExplainForHumans()` for query builders
13+
* `MysqlExplain::submitBuilder($builder)`
14+
* `MysqlExplain::submitQuery($connection, $sql, $bindings)`

‎LICENSE.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) tpetry <[email protected]>
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

‎README.md

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Laravel MySQL Explains For Humans
2+
3+
![License][icon-license]
4+
![PHP][icon-php]
5+
![Laravel][icon-laravel]
6+
[![Latest Version on Packagist][icon-version]][href-version]
7+
[![GitHub Unit Tests Action Status][icon-tests]][href-tests]
8+
[![GitHub Static Analysis Action Status][icon-staticanalysis]][href-staticanalysis]
9+
[![GitHub Code Style Action Status][icon-codestyle]][href-codestyle]
10+
11+
MySQL Query optimization with the `EXPLAIN` command is unnecessarily complicated: The output contains a lot of cryptic information that is incomprehensible or entirely misleading.
12+
13+
This Larvel package collects many query metrics that will be sent to [explainmysql.com](explainmysql.com) and transformed to be much easier to understand.
14+
15+
## Installation
16+
17+
You can install the package via composer:
18+
19+
```bash
20+
composer require tpetry/laravel-mysql-explain
21+
```
22+
23+
## Usage
24+
25+
### Query Builder
26+
27+
Three new methods have been added to the query builder for very easy submission of query plans:
28+
29+
| Type | Action |
30+
|------------------------|---------------------------------------------------------------------|
31+
| `explainForHumans` | returns URL to processed EXPLAIN output |
32+
| `dumpExplainForHumans` | dumps URL to processed EXPLAIN output and continue normal execution |
33+
| `ddExplainForHumans` | dumps URL to processed EXPLAIN output and stops execution |
34+
35+
36+
```php
37+
// $url will be e.g. https://explainmysql.com/explain/613cf8a0-d76c-4386-9680-5b6b537c3463
38+
$url = Film::where('description', 'like', '%astronaut%')
39+
->explainForHumans();
40+
41+
// URL to EXPLAIN will be printed to screen
42+
$users = Film::where('description', 'like', '%astronaut%')
43+
->dumpExplainForHumans()
44+
->get();
45+
46+
// URL to EXPLAIN will be printed to screen & execution is stopped
47+
$users = Film::where('description', 'like', '%astronaut%')
48+
->ddExplainForHumans()
49+
->get();
50+
```
51+
52+
### Raw Queries
53+
54+
In some cases you are executing raw SQL queries and don't use the query builder. You can use the `MysqlExplain` facade to get the EXPLAIN url for them:
55+
56+
```php
57+
use Tpetry\MysqlExplain\Facades\MysqlExplain;
58+
59+
// $url will be e.g. https://explainmysql.com/explain/89eef861-e01b-4ab1-8fa4-4f7dd9d33ead
60+
$url = MysqlExplain::submitQuery(
61+
DB::connection('mysql'),
62+
'SELECT * FROM actor WHERE first_name = ?',
63+
['PENEL\'OPE'],
64+
);
65+
```
66+
67+
## Testing
68+
69+
```bash
70+
composer test
71+
```
72+
73+
## Changelog
74+
75+
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
76+
77+
## Credits
78+
79+
- [Tobias Petry](https://github.com/tpetry)
80+
- [All Contributors](../../contributors)
81+
82+
## License
83+
84+
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
85+
86+
[href-codestyle]: https://github.com/tpetry/laravel-mysql-explain/actions/workflows/code-style.yml
87+
[href-staticanalysis]: https://github.com/tpetry/laravel-mysql-explain/actions/workflows/static-analysis.yml
88+
[href-tests]: https://github.com/tpetry/laravel-mysql-explain/actions/workflows/unit-tests.yml
89+
[href-version]: https://packagist.org/packages/tpetry/laravel-mysql-explain
90+
[icon-laravel]: https://img.shields.io/badge/Laravel-6.*--10.*-blue
91+
[icon-license]: https://img.shields.io/github/license/tpetry/laravel-mysql-explain?color=blue&label=License
92+
[icon-codestyle]: https://img.shields.io/github/actions/workflow/status/tpetry/laravel-mysql-explain/code-style.yml?label=Code%20Style
93+
[icon-php]: https://img.shields.io/packagist/php-v/tpetry/laravel-mysql-explain?color=blue&label=PHP
94+
[icon-staticanalysis]: https://img.shields.io/github/actions/workflow/status/tpetry/laravel-mysql-explain/static-analysis.yml?label=Static%20Analysis
95+
[icon-tests]: https://img.shields.io/github/actions/workflow/status/tpetry/laravel-mysql-explain/unit-tests.yml?label=Tests
96+
[icon-version]: https://img.shields.io/packagist/v/tpetry/laravel-mysql-explain.svg?label=Packagist
97+
98+
99+

0 commit comments

Comments
 (0)