Eloquent 모델 클래스

모델 컬렉션 이름 변경

기본적으로 이 모델은 모델 클래스 이름에 스네이크형 복수형을 사용합니다. 모델이 MongoDB에서 데이터를 검색하고 저장하는 데 사용하는 컬렉션의 이름을 변경하려면 모델 클래스의 $collection 속성을 재정의합니다.

다음 예제에서는 Planet 클래스에 대한 사용자 지정 MongoDB 컬렉션 이름 celestial_body 을 지정합니다.

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

$collection 속성 을 재정의하지 않고 이 모델은 planets 컬렉션 에 매핑합니다. 재정의된 속성 을 사용하면 예시 클래스는 celestial_body 컬렉션 에 모델을 저장합니다.

기본 키 필드 변경

MongoDB 문서를 고유하게 식별하는 모델의 기본 키 필드를 사용자 지정하려면 모델 클래스의 $primaryKey 속성을 재정의합니다.

기본값 으로 이 모델은 PHP MongoDB 운전자 를 사용하여 Laravel 애플리케이션 이 삽입하는 각 문서 에 대해 고유한 ObjectID를 생성합니다.

다음 예시에서는 name 필드를 Planet 클래스의 프라이머리 키로 지정합니다.

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

프라이머리 키 동작 및 사용자 지정 옵션에 대해 자세히 알아보려면 Eloquent 프라이머리 키 Docs 를 참조하세요. Laravel 에서 .

_id 필드, ObjectID 및 MongoDB 문서 구조에 대해 자세히 알아보려면 MongoDB 서버 의 문서 Docs 를 참조하세요.

일시 삭제 활성화

Eloquent에는 모델에서 delete() 메서드의 동작을 변경하는 일시 삭제 기능이 포함되어 있습니다. 모델에서 일시 삭제가 활성화된 경우 delete() 메서드는 데이터베이스에서 문서를 제거하는 대신 문서를 삭제된 것으로 표시합니다. deleted_at 필드에 타임스탬프를 설정하여 검색 작업에서 자동으로 제외합니다.

클래스에서 일시 삭제를 활성화 하려면 다음 코드 예시 와 같이 MongoDB\Laravel\Eloquent\SoftDeletes 트레이트를 추가합니다.

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

일시 삭제가 활성화된 모델에서 수행할 수 있는 메서드에 대해 알아보려면 Eloquent 소프트 삭제 Docs를 참조하세요. Laravel 에서 .

캐스트 데이터 유형

Eloquent를 사용하면 캐스팅 헬퍼를 사용하여 데이터를 저장하거나 검색하기 전에 모델 속성 데이터 유형을 변환할 수 있습니다. 이 헬퍼는 모델에서 동등한 접근자 및 변경자 메서드를 정의하는 대신 편리한 대안입니다.

다음 예제에서 캐스팅 헬퍼는 discovery_dt MongoDB에 MongoDB\BSON\UTCDateTime 으로 저장된 모델 속성을 datetime 변환합니다. 유형을 Laravel 유형으로 변환합니다.

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

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

이 변환을 사용하면 PHP DateTime 또는 탄소 클래스 이 필드의 날짜로 작업합니다. 다음 예제는 모델의 캐스팅 헬퍼를 사용하여 discovery_dt 가 3년 미만인 행성을 쿼리하는 Laravel 쿼리를 보여줍니다.

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

MongoDB의 데이터 유형에 학습 BSON types 보려면 MongoDB 서버 Docs 에서 를 참조하세요.

Laravel 캐스팅 헬퍼 및 지원되는 유형에 대해 자세히 알아보려면 속성 캐스팅 을 Docs참조하세요. Laravel 에서 .

대량 할당 사용자 지정

Eloquent를 사용하면 데이터 배열 을 create() 모델 메서드에 전달하여 여러 모델과 해당 모델의 속성 데이터를 생성할 수 있습니다. 여러 모델을 삽입하는 이 프로세스 를 대량 할당이라고 합니다.

대량 할당은 여러 모델을 생성하는 효율적인 방법이 될 수 있습니다. 그러나 악용 가능한 보안 취약점이 노출될 수 있습니다. 필드의 데이터에는 무단 권한 또는 액세스로 이어지는 업데이트가 포함되어 있을 수 있습니다.

Eloquent는 대량 할당 취약점으로부터 데이터를 보호하기 위해 다음과 같은 특성을 제공합니다.

• $fillable 대량 할당에서 쓰기 가능한 필드를 포함합니다.

• $guarded 대량 할당에서 무시되는 필드를 포함합니다.

다음 예제에서 모델은 $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);

데이터베이스에 저장된 모델에는 $fillable 속성에서 day_length 가 생략되었으므로 name 및 gravity 필드만 포함됩니다.

배열에서 생략된 필드를 채우려고 할 때 동작을 변경하는 방법을 알아보려면 $fillable 대량 할당 예외 를 Docs참조하세요. Laravel 에서 .

확장 클래스 예제

이 예시 에서는 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 $primaryKey = '_id';
    protected $keyType = 'string';
}

클래스를 정의한 후에는 평소대로 MongoDB 작업을 수행할 수 있습니다.

정리 가능한 예제

다음 정리 가능한 클래스에는 정리 작업이 삭제한 모델과 일치하는 prunable() 메서드와 일치하는 모델을 삭제하기 전에 실행되는 pruning() 메서드가 포함됩니다.

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\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);
    }
}

스키마 버전 관리 예시

이 샘플 상황에서는 다음 클래스에 의해 처음 모델링된 컬렉션 으로 작업하고 있습니다.

<?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 보다 작습니다. 문서 를 조회 하면 Laravel MongoDB 는 galaxy 필드 를 추가하고 스키마 버전을 현재 버전인 2 로 업데이트합니다.

"Saturn" 문서 에 schema_version 필드 가 포함되어 있지 않으므로 저장 시 Laravel MongoDB 가 현재 스키마 버전을 할당합니다.

마지막으로 이 코드는 컬렉션 에서 모델을 검색하여 변경 사항을 시연합니다.

// 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();