README

安装
跟踪可追踪模型的变化
视图模型
可保存文件模型
ICS 日历

安装

此包需要 PHP >= 7.3。使用 composer 安装此包

composer require timmcleod/laravel-core-lib

然后，在您的应用配置中（project/config/app.php）注册以下服务提供者，通过将它们添加到 providers 数组中

'providers' => [
    TimMcLeod\LaravelCoreLib\Providers\LaravelCoreLibServiceProvider::class,
    TimMcLeod\LaravelCoreLib\Providers\LaravelCoreLibArtisanServiceProvider::class,
]

跟踪可追踪模型的变化

跟踪 Eloquent 模型中发生的变化

此 trait 的目的是允许我们跟踪对 Eloquent 模型中属性值所做的更改，这样我们就可以在模型 保存后 访问这些更改。

如果您想将更改记录下来以供以后审查，这将非常有帮助。

要跟踪对 Eloquent 模型属性/字段所做的更改，只需将 ChangeTrackable trait 添加到您想要跟踪的模型中。如果您想限制跟踪的字段，只需添加一个名为 $trackable 的属性，如下所示。

use Illuminate\Database\Eloquent\Model;
use TimMcLeod\LaravelCoreLib\Database\Eloquent\ChangeTrackable;

class User extends Model
{
    use ChangeTrackable;
    
    protected $trackable = ['first_name', 'last_name'];
}

当您的模型被保存时，ChangeTrackable trait 将自动跟踪已更改的字段。以下方法可用于了解这些更改

/**
 * Returns true if any of the $trackable attributes have changed. If the
 * $trackable property evaluates as empty, this will return true if
 * any of the attributes' values have changed on the model.
 *
 * @return bool
 */
$model->hasTrackedChanges()

/**
 * Returns a string representation of the attributes that have changed. If a
 * property called $trackable exists on the model, then that $trackable
 * array is used to filter the attributes that should be serialized.
 *
 * If the $trackable property doesn't exist on the model or evaluates as empty,
 * then all of the tracked changes will be serialized without being filtered.
 *
 * @param string $format
 * @param string $delimiter
 * @param string $emptyOld
 * @param string $emptyNew
 * @return string
 */
$model->getTrackedChanges($format = '{attribute}: {old} > {new}', $delimiter = ' | ', $emptyOld = '', $emptyNew = '')

/**
 * Returns an array of the attributes that have changed. If a property called
 * $trackable exists on the model, then the $trackable array will be used
 * to limit or filter the attributes that are returned in the result.
 *
 * If the $trackable property doesn't exist on the model or evaluates as empty,
 * then all of the tracked changes will be returned without being filtered.
 *
 * @return array
 */
$model->getTrackedChangesArray()

/**
 * Returns true if any of the given attributes have changed on the model,
 * regardless of whether or not the $trackable property is defined on
 * the model.
 *
 * @param array $attributes
 * @return bool
 */
$model->hasAnyTrackedChangesFor($attributes = [])

/**
 * Returns a string representation of the attributes that have changed. If the
 * $attributes parameter evaluates as empty, then all tracked changes will
 * be serialized into a string without being filtered.
 *
 * @param array  $attributes
 * @param string $format
 * @param string $delimiter
 * @param string $emptyOld
 * @param string $emptyNew
 * @return string
 */
$model->getTrackedChangesFor($attributes = [], $format = '{attribute}: {old} > {new}', $delimiter = ' | ', $emptyOld = '', $emptyNew = '')

/**
 * Returns an array of the attributes that have changed. If the $attributes
 * parameter evaluates as empty, then all tracked changes are returned.
 *
 * @param array $attributes
 * @return array
 */
$model->getTrackedChangesArrayFor($attributes = [])

/**
 * Returns true if any of the model's attributes have changed, regardless
 * of whether or not the $trackable property is defined on the model.
 *
 * @return bool
 */
$model->hasAnyTrackedChanges()

/**
 * Returns a string representation of ALL of the attributes that have changed
 * on the model, even if the $trackable property does exist on the model.
 *
 * @param string $format
 * @param string $delimiter
 * @param string $emptyOld
 * @param string $emptyNew
 * @return string
 */
$model->getTrackedChangesForAll($format = '{attribute}: {old} > {new}', $delimiter = ' | ', $emptyOld = '', $emptyNew = '')

/**
 * Returns an array of the attributes that have changed. If the $trackable
 * property exists on the model, it's ignored, and all tracked changes
 * are always returned, regardless of whether $trackable exists.
 *
 * @return array
 */
$model->getTrackedChangesArrayForAll()

视图模型

使用视图模型清理混乱的视图

此包可以帮助您封装、验证和操作 Laravel 5.x 应用程序中每个视图所需的数据。

目的和概述

随着我们应用程序中视图的日益复杂，它们倾向于需要以不同方式呈现的更多数据。随着视图依赖项的增加和视图文件的日益复杂，跟踪视图所需的数据变得越来越困难。

视图模型通过以下方式帮助：

验证注入到视图中的数据，以验证数据是否正好符合视图的期望。
促进数据的捆绑，以及在实际的视图环境中操作数据的所需方法。
减少在您的视图中意外覆盖“全局”变量的可能性。
提供一种方法，可以一目了然地查看视图所需的数据。

入门

在注册了 LaravelCoreLibArtisanServiceProvider 之后，将可用一个新 Artisan 命令来生成您的视图模型。要创建新的视图模型，请使用 make:view-model Artisan 命令

php artisan make:view-model EditProfileViewModel

此命令将在您的 app/Http/ViewModels 目录中放置一个新的 EditProfileViewModel 类。如果该目录不存在，它将为您创建。

<?php

namespace App\Http\ViewModels;

use TimMcLeod\LaravelCoreLib\View\BaseViewModel;

class EditProfileViewModel extends BaseViewModel
{
    /** @var array */
    protected $rules = [];
}

如果您想对视图模型进行分组，您可以使用以下方式生成它们

php artisan make:view-model User/EditProfileViewModel

此命令将在您的 app/Http/ViewModels/User 目录中放置一个新的 EditProfileViewModel 类。

基本用法

要使用视图模型，只需创建视图模型的新实例，并将实例传递到视图中。

$vm = new EditProfileViewModel([
    'timezones' => Timezone::all(),
    'states'    => State::all(),
    'cities'    => City::all(),
    'user'      => Auth::user()
]);

return view('user.profile')->with('vm', $vm);

在您的视图中，您可以通过以下方式访问视图模型中的数据： $vm->timezones。

现在您可以在视图模型中添加自己的方法来将视图特定的逻辑与数据捆绑在一起，以保持视图的整洁。

// Inside of EditProfileViewModel class:

/**
 * Returns true if the user's timezone is the same as the given timezone.
 *
 * @param Timezone $timezone
 * @return bool
 */
public function isSelectedTimezone(Timezone $timezone)
{
    return $this->user->timezone === $timezone->code;
}

<!-- Inside of user.profile view -->

<select id="timezone" name="timezone">
    @foreach($vm->timezones as $timezone)
        <option value="{{$timezone->code}}" {{$vm->isSelectedTimezone($timezone) ? 'selected' : ''}}>{{$timezone->label}}</option>
    @endforeach
</select>

或者，也许您想在特定视图的 2 列中为城市创建一个复选框列表。您可以这样做

// Inside of EditProfileViewModel class:

/**
 * Returns the first half of cities from the cities array.
 *
 * @return array
 */
public function citiesCol1()
{
    $len = count($this->cities);
    return $this->cities->slice(0, round($len / 2));
}

/**
 * Returns the second half of cities from the cities array.
 *
 * @return array
 */
public function citiesCol2()
{
    $len = count($this->cities);
    return $this->cities->slice(round($len / 2));
}

<!-- Inside of user.profile view -->

<!-- Inside markup for column 1 -->
@foreach($vm->citiesCol1() as $city)
    <label><input name="cities[]" type="checkbox" value="{{$city->id}}">{{"$city->name, $city->state_code"}}</label>
@endforeach
    
<!-- Inside markup for column 2 -->
@foreach($vm->citiesCol2() as $city)
    <label><input name="cities[]" type="checkbox" value="{{$city->id}}"> {{"$city->name, $city->state_code"}}</label>
@endforeach

如您所见，视图模型允许我们将视图数据与在视图环境中操作数据的所需方法捆绑在一起。

可选地，在实例化新的视图模型时，可以使用在您的视图模型类中定义的规则来验证数据。您可以使用Laravel文档中定义的任何验证规则。

protected $rules = [
    'total' => 'required|integer',
    'name'  => 'required|string',
];

如果来自控制器的数据中有任何数据验证失败，将抛出异常。

< 侧记 >

如果需要此包，timmcleod/laravel-instance-validator，它将添加一些额外的验证规则，这些规则在您的视图模型中可能有助于验证接收到的数据。

这些规则在timmcleod/laravel-instance-validator中可用：instance_of、collection_of和paginator_of。

protected $rules = [
    'timezones' => 'required|collection_of:App\\Timezone',
    'states'    => 'required|collection_of:App\\State',
    'cities'    => 'present|collection_of:App\\City',
    'user'      => 'required|instance_of:App\\User',
];

< /侧记 >

可保存文件模型

TODO：编写有关与模型一起保存文件的实用信息

ICS 日历

TODO：编写有关使用ICS文件创建日历事件的实用信息

许可证

LaravelCoreLib for Laravel是开源软件，根据MIT许可证授权。

Laravel是Taylor Otwell的商标。

dgaitan / legacy-laravel-core-lib

维护者

详细信息