README

jStorage 库

安装

composer require shadoll/lantana

变更日志

版本 (1.2.4) 全局函数辅助器

新增

14.09.2019

在全局作用域中添加了2个辅助函数，以便更简单地访问服务。文件 src/Extensions/Guard/guardFunctions.php 通过 composer 连接（如果库已集成，可能需要更新自动加载文件 composer dump-autoload）
- lGuard() - 返回当前上下文 \Lantana\Extensions\Guard\GuardService（调用函数之前，服务应已加载，如下所述），相当于 \Lantana\Extensions\Guard\GuardService::context();
- lCustomer() - 返回绑定模型 \Lantana\Models\JSSharedCustomersServices 的辅助器，以及接口 \Lantana\Extensions\Guard\Contracts\BeSharedCustomerServices 的对象接口，目前这是 \Lantana\Extensions\Guard\Models\SharedCustomerServices（\Lantana\Extensions\Guard\GuardService 服务必须已加载）。
在接口 \Lantana\Extensions\Guard\Contracts\BeGuard 中添加了方法（返回接口 BeMainGuardModel 的原生模型 JS）
```
/**
 * @return BeMainGuardModel
 * */
public function getJSModel();
```

如有需要添加新功能，请在文件 src/Extensions/Guard/guardFunctions.php 中描述，在 header 中先阅读一些简短的建议。

版本 (1.2.2)

新增

10.09.2019

Lantana\Core\Exceptions\LantanaException 的额外数据从方法 getData(): mixed 返回接口对象 Lantana\Core\Contracts\BeAdditional 或 null 如果没有数据。目前实现用于处理请求 storeall、updateall、deleteall，分别返回 Lantana\Core\Exceptions\Additionals\Models\StoreAllData、Lantana\Core\Exceptions\Additionals\Models\UpdateAllData、Lantana\Core\Exceptions\Additionals\Models\DestroyAllData，从中我们可以获取相应的数据集合。

  $collect = JSSharedCustomersServices::all();

  $newCollectDestroy = $collect->filter(function ($item) {
      return $item->code == 'almond';
  });

  // получения дополнительных данных во время исключения
  try {
      $newCollectDestroy->destroy();
  } catch (\Lantana\Core\Exceptions\LantanaException $exception) {
      /**
       * @var Lantana\Core\Exceptions\Additionals\Models\DestroyAllData $destroyAllData
       */
      $destroyAllData = $exception->getData();

      echo $destroyAllData->deleted->toJson();

      $destroyAllData->skipped->each(function ($item) {
          // any action
      });

      $destroyAllData->not_found->isEmpty();
  }

09.09.2019

添加了克隆模型的功能
```
 $modelClone = clone $modelOriginal;
```
将方法 toArray() 返回到基本模型中
在 Lantana\Core\Exceptions\LantanaException 中添加了2个新方法 setData($data) 和 getData(): mixed 以在异常期间获取额外数据（例如，在大量创建、更新、删除模型时 - 在键 $strict=true 时可以查看哪些模型与 JStorage 存在冲突），

添加了用于批量处理集合的方法

在基本模型 Lantana\Model
- static store(Lantana\Extensions\Collection\Collection $collection, bool $strict = true): Lantana\Extensions\Collection\Collection,
- static update(Lantana\Extensions\Collection\Collection $collection, bool $strict = true): Lantana\Extensions\Collection\Collection,
- static destroy(Lantana\Extensions\Collection\Collection $collection, bool $strict = true): Lantana\Extensions\Collection\Collection,
在集合类 Lantana\Extensions\Collection\Collection
- store(bool $strict = true): Lantana\Extensions\Collection\Collection,
- update(bool $strict = true): Lantana\Extensions\Collection\Collection,
- destroy(bool $strict = true): Lantana\Extensions\Collection\Collection,

 $collect = JSSharedCustomersServices::all();

 $newCollectStore = $collect->map(function ($item) {
     return clone $item;
 });

 $newCollectUpdate = $collect->map(function ($item) {
     $item->code = 'any-code';
     return $item;
 });

 $newCollectDestroy = $collect->filter(function ($item) {
     return $item->code == 'almond';
 });

 // Массовое создание
 // используя статический метод модели
 // (обязательно модель должна быть того же класса что и модели внутри коллекции)
 JSSharedCustomersServices::store($newCollectStore);
 // или создание напрямую из коллекции
 $newCollectStore->store();

 // вторым параметром можно передать ключ при котором будет
 // применено нестрогие условия создания моделей
 // Если ключ будет true - JStrorage не создаст ниодную модель в базе
 // если хотья бы одна не удовлетворит правилам массового сохранения
 // В результате ошибки будет брошено исключение. В методе `getData()` `LantanaException`
 // можно посмотреть список моделей которые могли бы быть сохранены и список отброшеных моделей
 // Если ключ будет false - JStrorage создаст модели которые валидны для создания
 //
 // Все эти условия так же относятся и к массовом обновлении и массовом удалении моделей
 JSSharedCustomersServices::store($newCollectStore, false); // по умолчанию true
 $newCollectStore->store(false); // по умолчанию true

 // Массовое обновление
 // используя статический метод модели
 // (обязательно модель должна быть того же класса что и модели внутри коллекции)
 JSSharedCustomersServices::update($newCollectUpdate);
 // или обновление напрямую из коллекции
 $newCollectUpdate->update();

 // Массовое удаление
 // используя статический метод модели
 // (обязательно модель должна быть того же класса что и модели внутри коллекции)
 JSSharedCustomersServices::destroy($newCollectDestroy);
 // или удаление напрямую из коллекции
 $newCollectDestroy->destroy();

 // получения дополнительных данных во время исключения
 try {
     $newCollectDestroy->destroy();
 } catch (\Lantana\Core\Exceptions\LantanaException $exception) {
     print_r($exception->getData());
 }

优化了抛出异常的机制（所有异常都在库外处理）。

07.09.2019

所有在 版本 (1.0.1) 中列出的内容：
改进了创建包含嵌套模型和/或集合模型的集合的机制（特性 Lantana\Core\Helpers\CollectHelper），
删除了基本模型的方法 getFromEmbedded()（因为 _embedded 将自动存储来自模型或集合模型的模型或集合，见 本版本第2点），
在基本模型 Model 中添加了方法 __toString() 和 __isset，
添加了用于关系的辅助方法（特性 Lantana\Core\Helpers\RelationsHelper）
- withModel(string $model, string $foreign = null) (public)
- belongsToModel(string $model, string $local_key = null) (public)
- hasMany(string $class, string $local_key = null) (受保护的)
- belongsTo(string $class, string $foreign = null) (受保护的)
类 Lantana\Core\Request\Request 在请求中，使用 json 而不是 form_params,
添加了包 Lantana\Extensions\Guard
- 在 Guard 中使用的模型必须实现接口 Lantana\Extensions\Guard\Contracts\BeMainGuardModel（目前仅涉及 JSSharedCustomersServices、JSSharedApikeys、JSSharedPeriods、JSSharedAmocrm），

Core

模型类 (抽象)

方法

公共（处理模型）

save() - 保存模型（创建、更新）（返回 bool）

 // store
 $shared = new JSSharedCustomersServices();
 $shared->field = 'value';
 $shared->save();
 // update
 $shared = JSSharedCustomersServices::find('uuid');
 $shared->field = 'value';
 $shared->save();

delete() - 删除模型（《返回 bool）

 $shared = JSSharedCustomersServices::find('uuid');
 $shared->delete();

get()（别名 all()）- 获取模型集合（《返回 Lantana\Extensions\Collection\Collection）
```
 $shared = new JSSharedCustomersServices::where('field', 'value')->get();
 $sharedAll = JSSharedCustomersServices::all();
```
方法 all() 除了常规调用外，还有静态调用（示例中显示）。

find('uuid')（别名 findByUUID('uuid')）- 通过 UUID 获取模型（《返回 T extends Lantana\Model）

 // не очень красиво но возможность есть и так получить модель
 $shared1 = new JSSharedCustomersServices();
 $shared1->findByUUID('uuid');
 // так элегантнее
 $shared2 = JSSharedCustomersServices::find('uuid');

方法 find('uuid') 除了常规调用外，还有静态调用（示例中显示）。

first()、last() - 获取第一个或最后一个模型（《返回 T extends Lantana\Model）

$shared1 = JSSharedCustomersServices::where('field', 'value')->first();
$shared2 = JSSharedCustomersServices::where('field', 'value')->last();

select($fields = []) - 用于选择模型（们）的特定字段的查询构造器方法（《返回 T extends Lantana\Model）
```
$sharedModel = JSSharedCustomersServices::select(['field1', 'field2'])->first();
$sharedCollect = JSSharedCustomersServices::where('field', 'value')->select(['field1', 'field2'])->get();
```
方法 select($fields = []) 除了常规调用外，还有静态调用（示例中显示）。
where($field, $value)（别名 findByFieldValue($field, $value)）- 用于添加选择条件的查询构造器方法（过滤器）（《返回 T extends Lantana\Model）
```
$sharedModel = JSSharedCustomersServices::where('field', 'value')->where('field2', 'value2')->last();
$sharedCollect = JSSharedCustomersServices::where('field', 'value')->get();
```
方法 where($field, $value) 除了常规调用外，还有静态调用（示例中显示）。
getEntity() - 获取当前实体的字符串表示形式，
getBy[实体名称]() - 瓦西里在讲述（细节已忘记），

with(string $entity, string $foreign = null) - 用于添加与关联实体 一对一 的条件的查询构造器方法（《返回 T extends Lantana\Model）

$sharedModel = JSSharedCustomersServices::where('field', 'value')->with('shared-apikeys')->first();
$sharedCollect = JSSharedCustomersServices::where('field', 'value')->with('shared-apikeys')->with('shared-periods')->get();

belongs($entity, $local_key = null) - 用于添加与关联实体 一对多 的条件的查询构造器方法（《返回 T extends Lantana\Model）

$sharedModel = JSSharedCustomersServices::where('field', 'value')->belongs('almond-configs')->first();
$sharedCollect = JSSharedCustomersServices::where('field', 'value')->belongs('almond-configs')->belongs('other-entity')->get();

withModel(string $model, string $foreign = null) - 用于添加与关联实体 一对一 的条件的查询构造器方法（与 with 方法不同的是，第一个参数是表示要绑定模型的类名称的字符串）（《返回 T extends Lantana\Model）

$sharedModel = JSSharedCustomersServices::where('field', 'value')->withModel('Lantana\Models\JSSharedApikeys')->first();
$sharedCollect = JSSharedCustomersServices::where('field', 'value')->withModel('Lantana\Models\JSSharedApikeys')->withModel('App\Models\JSOtherClass')->get();

belongsToModel(string $model, string $local_key = null) - 用于添加与关联实体 一对多 的条件的查询构造器方法（与 belongs 方法不同的是，第一个参数是表示要绑定模型的类名称的字符串）（《返回 T extends Lantana\Model）

$sharedModel = JSSharedCustomersServices::where('field', 'value')->belongsToModel('Lantana\Models\JSAlmondConfigs')->first();
$sharedCollect = JSSharedCustomersServices::where('field', 'value')->belongsToModel('Lantana\Models\JSAlmondConfigs')->belongsToModel('App\Models\JSOtherClass')->get();

受保护的方法（用于扩展功能）
- hasMany(string $class, string $local_key = null) - 用于获取与关联实体 一对多 的关联实体（在特定模型类中可扩展）的方法（该方法的特性是它懒加载和返回数据，即如果关联集合存在，则返回它，如果不存在，则从服务器加载并返回）（《返回 \Lantana\Extensions\Collection\Collection）
```
class JSSharedApikeys extends Model implements BeCollectionModel
{

      public function sharedCustomersServices()
      {
          return $this->hasMany('Lantana\Models\JSSharedCustomersServices');
      }
}

// гдето в коде
$sharedCustomersServicesModel = JSSharedApikeys::find('uuid')->sharedCustomersServices();
```
- belongsTo(string $class, string $foreign = null) - 用于获取与关联实体 一对一 的关联实体（在特定模型类中可扩展）的方法（该方法的特性是它懒加载和返回数据，即如果关联实体存在，则返回它，如果不存在，则从服务器加载并返回）（《返回 T extends Lantana\Model）
```
class JSSharedCustomersServices extends Model implements BeCollectionModel
{

      public function sharedApikeys()
      {
          return $this->belongsTo('Lantana\Models\JSSharedApikeys');
      }
}

// гдето в коде
$sharedApikeysModel = JSSharedCustomersServices::find('uuid')->sharedApikeys();
```
  可以在 Lantana\Models\{JSSharedCustomersServices, JSSharedApikeys, JSSharedAmocrm, JSSharedPeriods} 类中查看 hasMany 和 belongsTo 方法的示例。

类 \Lantana\Extensions\Collection\Collection

方法

有很多方法，请参阅Illuminate\Support\Collection；

处理服务 \Lantana\Extensions\Guard\GuardService

为了简单地将服务集成到laravel和Lumen框架中

在应用程序中注册 Lantana\Extensions\Guard\Lara\Providers\ServiceProvider（Laravel -> 在config/app.php的providers部分添加Lantana\Extensions\Guard\Lara\Providers\ServiceProvider::class,）(Lumen -> 在bootstrap/app.php中添加$app->register(Lantana\Extensions\Guard\Lara\Providers\ServiceProvider::class);)，

您可以在应用程序的任何位置自行初始化服务，或添加现有的Middleware Lantana\Extensions\Guard\Lara\Middlewares\Authenticate，该Middleware将加载服务并可以为您的应用程序加载额外的数据（如果Lantana\Extensions\Guard\Lara\Middlewares\Authenticate不符合要求，可以创建自己的中间件，继承Lantana\Extensions\Guard\Lara\Middlewares\BaseGuard并在isAuth()方法中定义逻辑）。将Middleware添加到应用程序 - (Laravel -> 在App\Http\Kernel的$middleware属性中为所有路由或$routeMiddleware为特定路由添加

    protected $middleware = [
         \App\Http\Middleware\CheckForMaintenanceMode::class,
         \Illuminate\Foundation\Http\Middleware\ValidatePostSize::class,
         \App\Http\Middleware\TrimStrings::class,
         \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
         \App\Http\Middleware\TrustProxies::class,
         \Barryvdh\Cors\HandleCors::class,

         \Lantana\Extensions\Guard\Lara\Middlewares\Authenticate::class, // <- тут
     ];

     protected $routeMiddleware = [
         'auth' => \App\Http\Middleware\Authenticate::class,
         'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
         'bindings' => \Illuminate\Routing\Middleware\SubstituteBindings::class,
         'cache.headers' => \Illuminate\Http\Middleware\SetCacheHeaders::class,
         'can' => \Illuminate\Auth\Middleware\Authorize::class,
         'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
         'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
         'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
         'verified' => \Illuminate\Auth\Middleware\EnsureEmailIsVerified::class,

         'guard' => \Lantana\Extensions\Guard\Lara\Middlewares\Authenticate::class, // <- тут
     ];

) (Lumen -> 在bootstrap/app.php中添加

 // для всех роутов
 $app->middleware([
     \Lantana\Extensions\Guard\Lara\Middlewares\Authenticate::class,
 ]);

 // для конкретных роутов
 $app->routeMiddleware([
  'guard' => Lantana\Extensions\Guard\Lara\Middlewares\Authenticate::class,
 ]);

在控制器构造器、方法或其他方便的位置

 //...
 use Lantana\Extensions\Guard\GuardService;

 class ExampleController extends Controller
 {
      private $guardService;

      public function __construct(GuardService $guardService)
      {
          $this->guardService = $guardService;
      }

      public function index()
      {
          try {
              $this->guardService
                ->validApikey('apikey')
                ->validPeriod()
                ->validAmocrm();

              // is valid, other actions
              return 'ok';
          } catch (GuardingException $guardingException) {
              \Log::error('#FK.SECURITY:: ' . $guardingException->getMessage());
          }

          return 'error';
      }
 }

在应用程序的.env文件中，您可以通过APP_CONFIG_TABLES属性列出所有要随服务初始化自动加载的实体，通过逗号分隔（没有空格）：APP_CONFIG_TABLES=almond-configs,other-entity（实体类应该在Lantana\Models目录中），或者通过APP_CONFIG_MODELS属性列出所有实体类的名称，通过逗号分隔（没有空格）：APP_CONFIG_MODELS=Lantana\Models\JSAlmondConfigs,App\XYZ\JSMyModel（相应的模型类可以位于任何位置，只要遵守psr-4规则即可）（条件 - 实体必须引用shared-customers-services），可以通过Lantana\Extensions\Guard\GuardService服务获取数据

如前所述，您可以通过Lantana\Extensions\Guard\Lara\Middlewares\BaseGuard或没有它来自定义服务的初始化和操作方式。

.env

为了方便库的使用，可以在.env文件中添加环境变量JSTORAGE_URI，其中包含对JStorage服务器的链接，以及JSTORAGE_APIKEY，它是访问JStorage服务器的访问密钥（如果使用静态模型上下文，则此条件是强制性的），并且（如有必要）按照上述方式添加环境变量APP_CONFIG_TABLES和APP_CONFIG_MODELS。

带有集合的版本（1.0.1）

新增

所有模型都自动序列化为JSON（实现JsonSerializable接口），
基本模型的整体逻辑分散到特质中（在Lantana\Core\Helpers包中）。
Data、Request、RequestData、RequestParams类已移至Lantana\Core\Request包。
创建了异常类Core\Exceptions\LantanaException。
将基本模型Base和Model合并为公共的Model，（Model类是抽象的，以保障安全）。
已删除方法toArray()、current()、next()、key()、valid()、rewind()（它们的功能已经消失）。
where()、select()、all()、find()方法也可以在静态上下文中调用（在获取模型（集合）时很方便，例如JSSharedCustomersServices::all()将返回对象集合Lantana\Extensions\Collection\Collection，JSSharedCustomersServices::where('customer_id', '1')->get()将返回带有过滤条件的集合） -- 条件是存在.env文件，因为这需要基本模型的构造器。
模型必须实现接口Lantana\Extensions\Collection\Contracts\BeCollectionModel才能成为集合的一部分（目前并不十分合理，可能是出于安全考虑）。

shadoll / latoexst

维护者

详情