/ /

エラスティックモデルクラス

Overview

このガイドでは、Lambel MongoDB を使用して Lambel Eloquet モデルを定義およびカスタマイズする方法を説明します。 Lambda Eloqueent オブジェクト関係マッパー（ORM）を使用することで、これらのモデルを使用して MongoDB データを操作できます。

次のセクションでは、Lambel MongoDB モデルに Lambel Eloqueent ORM の動作を追加する方法について説明します。

「楕円モデルクラスの定義」では、モデルクラスの作成方法が示されています。
「認証可能なモデルの拡張」では、認証ユーザーとして MongoDB を設定する方法が示されています。
「効率的なモデルクラスのカスタマイズ」では、いくつかのモデルクラスのカスタマイズについて説明しています。
「サードパーティモデルクラスの拡張」では、サードパーティのモデルクラスを MongoDB と互換性を持たせるために方法について説明しています。
「プルーニング動作を指定する」では、不要になったモデルを定期的に削除する方法が示されます。
「バージョン管理されたモデルスキーマの作成」では、モデルスキーマのバージョン管理を実装する方法が示されています。

冗長なモデルクラスの定義

等価モデルは、データを表すクラスです。挿入、アップデート、削除などのデータベース操作を実行するメソッドが含まれます。

Lambel MongoDB モデルを宣言するには、次のコード例に示すように、 MongoDB\Laravel\Eloquent\Modelを拡張する Laravel アプリケーションのapp/Modelsディレクトリにクラスを作成します。

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
}

デフォルトでは、モデルは Lambda アプリケーションのconfig/database.php設定で設定されている MongoDB database 名と、コレクションのモデルクラス名であるスニペットの複数形を使用します。

このモデルはplanets MongoDB コレクションに保存されています。

Tip

または、artisan コンソールを使用してモデルクラスを生成し、Illuminate\Database\Eloquent\Model のインポートを MongoDB\Laravel\Eloquent\Model に変更します。artisan コンソールの詳細については、Lambel ドキュメントの「アーティファクトコンソール」を参照してください。

Lambda アプリケーションが使用するデータベース名を指定する方法については、「 MongoDB 接続の構成」を参照してください。

注意

MongoDB常にプライマリキー値を _idフィールドに保存します。このフィールドは、モデル内で $id としてアクセスされます。クエリビルダを使用すると、Lambda 統合はクエリ内の id を _id に変換します。これにより、 idフィールドを使用する他の Lambda コンポーネントとの互換性が確保されます。識別子タイプをカスタマイズするには、モデルの $keyTypeプロパティを設定し、モデルを保存する前に値を割り当てます。

認証可能なモデルを拡張する

MongoDB を Lambel ユーザープロバイダーとして構成するには、Lambel 統合MongoDB\Laravel\Auth\Userクラスを拡張します。次のコード例は、このクラスを拡張する方法を示しています。

<?php
namespace App\Models;
use MongoDB\Laravel\Auth\User as Authenticatable;
class User extends Authenticatable
{
}

Lambel認証ユーザープロバイダーをカスタマイズする方法の詳細については、Lambel ドキュメントの「カスタムユーザープロバイダーの追加」を参照してください。

効率的なモデルクラスをカスタマイズする

このセクションでは、次の Elastic モデル動作のカスタマイズを実行する方法について説明します。

モデルコレクション名の変更
ソフト削除の有効化
データ型のキャスト
一括割り当てをカスタマイズ

モデルコレクション名の変更

デフォルトでは、モデルはモデルクラス名のスニペットケースの複数形を使用します。モデルが MongoDB でデータを検索して保存するために使用するコレクションの名前を変更するには、モデルクラスの$tableプロパティをオーバーライドします。

注意

モデルとコレクション間の関連付けをわかりやすくするために、デフォルトのコレクション命名動作を使用することをお勧めします。

次の例では、 Planetクラスに対してカスタム MongoDB コレクション名celestial_bodyを指定します。

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $table = 'celestial_body';
}

$tableプロパティをオーバーライドせず、このモデルはplanetsコレクションにマッピングします。オーバーライドされたプロパティを使用すると、サンプルクラスはモデルをcelestial_bodyコレクションに保存します。

ソフト削除の有効化

Elastic には、モデルのdelete()メソッドの動作を変更するソフト削除機能が含まれています。モデルでソフト削除が有効になっている場合、 delete()メソッドはドキュメントをデータベースから削除するのではなく、削除済みとしてマークします。 deleted_atフィールドにタイムスタンプを設定して、検索操作から自動的に除外します。

クラスでソフト削除を有効にするには、次のコード例に示すようにIlluminate\Database\Eloquent\SoftDeletesトランザクションを追加します。

<?php
namespace App\Models;
use Illuminate\Database\Eloquent\SoftDeletes;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    use SoftDeletes;
}

ソフト削除が有効になっているモデルで実行できるメソッドの詳細については、Lambel ドキュメントの「効率的なソフト削除」を参照してください。

データ型のキャスト

Elastic では、キャスティングヘルパーを使用してデータを保存または取得する前に、モデル属性データ型を変換できます。このヘルパーメソッドは、モデルに同等のアクセスメソッドとミューテーションメソッドを定義するのに便利な代替手段です。

次の例では、キャパシティーヘルパーは、 MongoDB$\ BSONdiscovery_dt \\UTCDateTime 型としてMongoDBに保存されているモデル属性を Lambeldatetime 型に変換します。

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $casts = [
        'discovery_dt' => 'datetime',
    ];
}

Tip

Lambel 11のキャスト

Laravel 11 以降では、$casts 属性を使用する代わりに casts() メソッドを定義して、データ型変換を指定できます。次のコードでは、casts() メソッドを使用して、前の例と同じ変換を実行します。

protected function casts(): array
{
   return [
      'discovery_dt' => 'datetime',
   ];
}

詳細については、Lambda ドキュメントの属性キャスティングを参照してください。

この変換により、 PHPのDateTimeクラスを使用して、このフィールドの日付を操作できるようになります。次の例では、モデルのキャスティングヘルパーを使用して、discovery_dt が 3 年前より小さい惑星をクエリする Lambda クエリを示します。

Planet::where( 'discovery_dt', '>', new DateTime('-3 years'))->get();

注意

カード日付クラス

Lambda MongoDB v5.0 以降、UTCDateTime MongoDBのBSON値は、クエリ結果のカード日付クラスとして返されます。Lambda 統合は、この変換を実行するときにデフォルトのタイムゾーンを適用します。

MongoDBデータ型の詳細については、サーバーマニュアルの「 BSON Types 」を参照してください。

Lambel キャパシティーヘルパーとサポートされているタイプの詳細については、Lalavel ドキュメントの「属性キャパシティー」を参照してください。

重要

Lambda MongoDB v5.8 以降では、array キャスト型は非推奨です。キャストタイプとしてarray を使用すると、ネイティブBSON形式ではないMongoDBにJSONでエンコードされた文字列として属性値が保存されます。移行オプションを含む詳細については、「 5.8バージョンの非推奨」を参照してください。

一括割り当てをカスタマイズ

Elastic では、データの配列をcreate()モデルメソッドに渡すことで、複数のモデルとその属性データを作成できます。複数のモデルを挿入するこのプロセスは、一括割り当てと呼ばれます。

一括割り当ては、複数のモデルを作成する効率的な方法です。ただし、利用可能なセキュリティの脆弱性が生じる可能性があります。フィールドのデータには、不正な権限やアクセスにつながる更新が含まれている可能性があります。

Eloquert は、一括割り当ての脆弱性からデータを保護するために、次の機能を提供します。

$fillable 一括割り当てで書き込み可能なフィールドが含まれています
$guarded 一括割り当てで無視されるフィールドが含まれます

重要

脆弱性から保護するために、$guarded ではなく $fillable を使用することを推奨します。この推奨事項の詳細については、セキュリティリリース: Lalavel 6.18.35、7.24.0 を参照してください。Lambda サイトの記事。

次の例では、モデルでは$fillable属性を使用してフィールドの一括割り当てが許可されています。

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $fillable = [
        'name',
        'gravitational_force',
        'diameter',
        'moons',
    ];
}

次のコード例は、 Planetモデルの一括割り当てを示しています。

$planets = [
    [ 'name' => 'Earth', 'gravitational_force' => 9.8, 'day_length' => '24 hours' ],
    [ 'name' => 'Mars', 'gravitational_force' => 3.7, 'day_length' => '25 hours' ],
];
Planet::create($planets);

データベースに保存されるモデルには、name gravityday_length$fillable属性からが省略されているため、フィールドとフィールドのみが含まれます。

配列から省略されたフィールドを入力する際の動作を変更する方法については、Lambda $fillableドキュメントの「一括割り当ての例外」を参照してください。

サードパーティのモデルクラス拡張

Lambda 統合を使用して、モデルクラスを定義するときにDocumentModel特権を含めることで、サードパーティのモデルクラスを拡張できます。この特権を含めることで、サードパーティのクラスを MongoDB と互換性のあるものにすることができます。

モデルクラスにDocumentModel特権を適用する場合は、Lambda 統合が MongoDB ObjectIdの値をstring型にキャストするため、 $keyTypeプロパティを'string'に設定する必要があります。

拡張クラスの例

この例では、 ThirdPartyPackageというパッケージからCelestialBodyクラスを拡張するPlanetモデルクラスを作成します。 PostクラスにはDocumentModel特権が含まれ、 $primaryKeyや$keyTypeなどのプロパティが定義されます。

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\DocumentModel;
use ThirdPartyPackage\CelestialBody;
class Planet extends CelestialBody
{
    use DocumentModel;
    protected $fillable = ['name', 'diameter'];
    protected $keyType = 'string';
}

クラスを定義した後は、通常どおり MongoDB 操作を実行できます。

Tip

DocumentModel特権を使用する別の例については、ユーザー認証ガイドの「 Lambda認証」セクションを参照してください。

プルーニング動作を指定する

不要になったモデルデータを定期的に削除するための基準を指定できます。 model:pruneコマンドをスケジュールまたは実行すると、Lambda は、削除するモデルを一致させるために、 PrunableとMassPrunable特権をインポートするすべてのモデルでprunable()メソッドを呼び出します。

MongoDB をデータベースとして使用するモデルでこの機能を使用するには、適切なインポートをモデルに追加します。

Illuminate\Database\Eloquent\Prunable 条件に一致するモデルを削除する前に、オプションでクリーンアップステップを実行します
MongoDB\Laravel\Eloquent\MassPrunable は、モデルデータを取得せずに条件に一致するモデルを削除します。

注意

一括実行可能なモデルでソフト削除を有効にする場合は、次の Lambda MongoDB パッケージをインポートする必要があります。

Illuminate\Database\Eloquent\SoftDeletes
MongoDB\Laravel\Eloquent\MassPrunable

プルーニング機能の詳細については、Lambel ドキュメントのプルーニングモデルを参照してください。

実行可能な例

次のプル可能なクラスには、プルーニングアクションが削除するモデルに一致するprunable()メソッドと、一致するモデルを削除する前に実行されるpruning()メソッドが含まれています。

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use Illuminate\Database\Eloquent\Prunable;
class Planet extends Model
{
    use Prunable;
    public function prunable()
    {
        // matches models in which the solar_system field contains a null value
        return static::whereNull('solar_system');
    }
    protected function pruning()
    {
        // Add cleanup actions, such as logging the Planet 'name' attribute
    }
}

大量実行可能な例

次の一括プル可能なクラスには、プルーニングアクションが削除するモデルに一致するprunable()メソッドが含まれています。

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\MassPrunable;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    use MassPrunable;
    public function prunable()
    {
        // matches models in which the gravitational_force field contains
        // a value greater than 0.5
        return static::where('gravitational_force', '>', 0.5);
    }
}

バージョン管理されたモデルスキーマの作成

Eloqueent モデルでHasSchemaVersion特権を使用することで、スキーマのバージョン管理パターンをアプリケーションに実装できます。異なるスキーマを持つデータを含むコレクションを整理または標準化するために、スキーマバージョンを実装することを選択できます。

Tip

スキーマのバージョン管理の詳細については、サーバーマニュアルの「スキーマのバージョン管理のためのモデルデータ」チュートリアルを参照してください。

MongoDB をデータベースとして使用するモデルでこの機能を使用するには、 MongoDB\Laravel\Eloquent\HasSchemaVersionインポートをモデルに追加します。次に、 SCHEMA_VERSION定数を1に設定して、コレクションの最初のスキーマバージョンを設定します。コレクションが展開して複数のスキーマを含む場合は、後続のモデルクラスでSCHEMA_VERSION定数の値を更新できます。

モデルを作成する際、モデルを取得するときに現在のスキーマバージョンへの移行を指定するためのmigrateSchema()メソッドを定義できます。このメソッドでは、古いモデルに加える変更を指定して、現在のスキーマバージョンと一致するようにモデルを更新できます。

スキーマバージョンが指定されていないモデルを保存すると、 HasSchemaVersion特権は最新のスキーマバージョンに準拠していると想定します。 schema_versionフィールドを含まないモデルを検索すると、trait はスキーマバージョンが0であると想定し、移行を実行します。

スキーマのバージョン管理の例

このサンプル状況では、最初に次のクラスによってモデル化されたコレクションを操作しています。

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $fillable = ['name', 'type'];
}

ここで、コレクションに新しいスキーマバージョンを実装します。次の動作を持つ新しいモデルクラスを定義できます。

HasSchemaVersion特権を実装し、現在のSCHEMA_VERSIONを2に設定します
スキーマバージョンが2未満のモデルを'Milky Way'の値を持つgalaxyフィールドに移行するためのmigrateSchema()メソッドを定義します。

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\HasSchemaVersion;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    use HasSchemaVersion;
    public const SCHEMA_VERSION = 2;
    protected $fillable = ['name', 'type', 'galaxy'];
    /**
     * Migrate documents with a lower schema version to the most current
     * schema when inserting new data or retrieving from the database.
     */
    public function migrateSchema(int $fromVersion): void
    {
        if ($fromVersion < 2) {
            $this->galaxy = 'Milky Way';
        }
    }
}

次のコードの"WASP-39 b"ドキュメントでは、 schema_versionフィールドの値は2より小さいです。ドキュメントを取得すると、Lambda 統合はgalaxyフィールドを追加し、スキーマバージョンを現在のバージョン2に更新します。

"Saturn"ドキュメントにはschema_versionフィールドが含まれていないため、Laravel 統合は保存時に現在のスキーマバージョンをそのドキュメントに割り当てます。

最後に、コードはコレクションからモデルを検索し、変更を示します。

// Simulates a document in the collection with schema version 1
Planet::insert([
    [
        'name' => 'WASP-39 b',
        'type' => 'gas',
        'schema_version' => 1,
    ],
]);
// Saves a document with no specified schema version
$saturn = Planet::create([
    'name' => 'Saturn',
    'type' => 'gas',
]);
// Retrieves both models from the collection
$planets = Planet::where('type', 'gas')
    ->get();

[
  {
    "_id": ...,
    "name": "WASP-39 b",
    "type": "gas",
    "galaxy": "Milky Way",
    "schema_version": 2,
  },
  {
    "_id": ...,
    "name": "Saturn",
    "type": "gas",
    "schema_version": 2,
  }
]

戻る

時系列

関係

エラスティック モデル クラス