README

此包为您提供了使用 Laravel 项目的一些附加、便捷的宏。

安装

使用 Composer 安装此包

composer require sirmathays/convenient-laravel-macros

包会自动注册自己。

宏

以下是包提供的宏的简要文档。

• Illuminate\Database\Eloquent\Builder
  • selectKey
  • whereLike & orWhereLike
• Illuminate\Database\Query\Builder
  • selectRawArr
• Illuminate\Support\Collection
  • mergeMany
  • pluckMany
  • whereExtends
  • whereImplements
  • whereUses
• Illuminate\Support\Arr
  • combine
  • fillKeys
  • join
  • zip
  • unzip
• Illuminate\Support\Str
  • wrap
• Illuminate\Support\Stringable
  • wrap
• Carbon\CarbonPeriod
  • collect

Illuminate\Database\Eloquent\Builder::selectKey

在查询中选取模型的键（使用模型的 getKey 方法）。

$query = User::query()->selectKey();

$query->toSql() // "select `id` from `users`"

Illuminate\Database\Eloquent\Builder::whereLike & orWhereLike

$query = User::query()
    ->whereLike('name', 'Matti Suo', 'right')
    ->orWhereLike('name', 'ranie');
    ->orWhereLike('name', 'mi', 'left');

$query->toSql(); // "select * from `users` where (`name` LIKE ?) or (`name` LIKE ?) or (`name` LIKE ?)"
// First ? being "Matti Suo%", second "%ranie%" and third "%mi"

$query = User::query()->whereLike('games.name', 'Apex Leg', 'right');

$query->toSql(); 
// select * from `users` where (exists (select * from `games` where `users`.`id` = `games`.`user_id` and `name` LIKE ?))
// ? being "Apex Leg%"

Illuminate\Database\Query\Builder::selectRawArr

将原始选择语句作为数组添加，而不是作为丑陋的字符串（selectRaw）。

$query = User::query()->selectRawArr([
    'concat(`id`, "-", `name`) as id_name'
    'concat(`email`, "-", `name`) as email_name'
]);

$query->first()->toArray() // ["id_name" => "1-Matti", "email_name" => "matti@suoraniemi.com-Matti"]

// VS

$query = User::query()->selectRaw('concat(`id`, "-", `name`) as id_name, concat(`email`, "-", `name`) as email_name');

Illuminate\Support\Collection::mergeMany

一次性将多个数组/集合合并到集合中。

$data = new Collection([1,2,3]);

$data->mergeMany([4], [5], [6]); // [1, 2, 3, 4, 5, 6]

Illuminate\Support\Collection::pluckMany

从集合项中选取多个键。

$data = User::query()->get();

$data->pluckMany('id', 'name')->toArray(); // [["id" => 1, "name" => "Matti Suoraniemi"]]

Illuminate\Support\Collection::whereExtends

过滤扩展给定类的类和/或对象。

use Illuminate\Database\Eloquent\Model;

$data = new Collection([
    \App\Models\User::class,
    \App\Models\Game::class,
    \App\Models\Console::class,
    \App\Models\Hobby::class,
]);

$data->whereExtends(Model::class)->count(); // 4

Illuminate\Support\Collection::whereImplements

过滤实现给定接口的类和/或对象。

use App\Contracts\PlayableOnConsole;

$data = new Collection([
    \App\Models\User::class,
    \App\Models\Game::class,
    \App\Models\Console::class,
    \App\Models\Hobby::class,
]);

$data->whereImplements(PlayableOnConsole::class)->toArray(); // ["App\Models\Game"]

Illuminate\Support\Collection::whereUses

过滤使用给定特性的类和/或对象。

use Illuminate\Notifications\Notifiable;

$data = new Collection([
    \App\Models\User::class,
    \App\Models\Game::class,
    \App\Models\Console::class,
    \App\Models\Hobby::class,
]);

$data->whereUses(Notifiable::class)->toArray(); // ["App\Models\User"]

Illuminate\Support\Arr::associate

通过将任何具有整数键的值转换为填充给定填充值的键值对，将数组转换为完全关联数组。具有字符串键的值将保持不变。

Arr::associate(['foo']) // ["foo" => null]
Arr::associate(['foo', 'bar' => []], []) // ["foo" => [], "bar" => []]
Arr::associate(['foo', 'bar' => []], fn () => Arr::random(['foo', 'bar'])) // ["foo" => "foo", "bar" => []]
Arr::associate([fn () => Str::reverse('foo'), 'bar' => []]) // ["oof" => null, "bar" => []]

Illuminate\Support\Arr::combine

类似于 array_combine，但允许有比值更多的键。没有值的键将被设置为 null。

Arr::combine(['foo', 'zoo'], ["bar", "gar"]) // ["foo" => "bar", "zoo" => "gar"]
Arr::combine(['foo', 'zoo'], ["bar"]) // ["foo" => "bar", "zoo" => null]

Illuminate\Support\Arr::fillKeys

用给定的值填充给定的键。您还可以设置只有已存在于数组中的键才能被填充。换句话说，如果键 foo 要用值 bar 填充，但键 foo 不已存在于数组中，数组将保持不变。

$array = ['foo' => 'bar', 'zoo' => 'gar'];

Arr::fillKeys($array, ['foo', 'zoo'], null) // ["foo" => null, "zoo" => null]
Arr::fillKeys($array, ['foo', 'zoo', 'boo'], null) // ["foo" => null, "zoo" => null, "boo" => null]
Arr::fillKeys($array, ['foo', 'zoo', 'boo'], null, true) // ["foo" => null, "zoo" => null]

Illuminate\Support\Arr::join

将集合的优雅连接方法引入 Arr。

Arr::join(['foo', 'bar', 'zoo'], ', ', ' and ') // "foo, bar and zoo"

Illuminate\Support\Arr::zip

使用给定的 zipper 将键和值组合在一起。

Arr::zip(['foo' => 'bar', 'zoo' => 'gar'], ':') // ["foo:bar", "zoo:gar"]

Illuminate\Support\Arr::unzip

使用给定的 zipper 将键解包为键和值。

Arr::unzip(['foo:bar', 'zoo:gar'], ':') // ["foo" => "bar", "zoo" => "gar"]

Illuminate\Support\Str::wrap

用给定的字符(们)包裹字符串。

Str::wrap('foo', ':') // ":foo:"
Str::wrap('bar', '<', '>') // "<bar>"
Str::wrap('!zoo', '!') // "!zoo!"

Illuminate\Support\Stringable::wrap

用给定的字符(们)包裹字符串。

(string) Str::of('foo')->upper()->wrap(':') // ":FOO:"
(string) Str::of('bar')->upper()->wrap('<', '>') // "<BAR>"
(string) Str::of('!zoo')->upper()->wrap('!') // "!ZOO!"

Carbon\CarbonPeriod::collect

$dates = CarbonPeriod::between('yesterday', 'today')->collect();

$dates->first()->toDateTimeString() // "2022-06-14 00:00:00"

扩展 MacroServiceProvider

您可以通过扩展此包提供的 MacroServiceProvider 类来创建自己的宏服务提供商！

以下是一个示例

<?php

namespace App\Providers;

use SirMathays\Convenience\Foundation\MacroServiceProvider as ServiceProvider;

class MacroServiceProvider extends ServiceProvider
{
    protected static array $macros = [
        \Illuminate\Support\Collection::class => [
            'example' => \App\Macros\ExampleMacro::class
        ]
    ];
}

上述示例中引用的宏类看起来可能像这样

<?php

namespace App\Macros;

class ExampleMacro
{
    public function __invoke(): \Closure
    {
        return function () {
            // Something cool worth getting macroed happens here...
            return $this;
        }
    }
}

命令

您可以使用 make:macro <name> 来生成一个宏文件，以帮助您构建结构。该命令支持 --mixin 选项（例如：--mixin=/Illuminate/Support/Collection）。这将向宏类声明上方添加一个带有 @mixin 标签的 PHP 文档块。

此包还包括 macro:generate 命令。如果您已设置扩展 SirMathays\Convenience\Foundation\MacroServiceProvider 类的提供者类，该命令将遍历提供者中定义的宏，并生成缺失的宏。这样，您可以定义多个已知将使用的宏，然后批量生成它们。其行为与 Laravel 的 event:generate 非常相似。

例如

<?php

namespace App\Providers;

use SirMathays\Convenience\Foundation\MacroServiceProvider as ServiceProvider;

class MacroServiceProvider extends ServiceProvider
{
    protected static array $macros = [
        \Illuminate\Support\Collection::class => [
            'example' => \App\Macros\ExampleMacro::class
        ]
    ];
}

假设 ExampleMacro 尚未存在，则该命令将生成宏类，并自动填充 @mixin 标签。

许可证

Convenient Laravel Commands 是开源软件，许可协议为 MIT 许可证。