eloquent sortable

Eloquent 모델의 정렬 가능한 동작

이 패키지는 Eloquent 모델에 정렬 가능한 동작을 추가하는 특성을 제공합니다.

모델의 새 레코드의 순서 열 값은 해당 모델의 모든 레코드 순서 열의 최대값 + 1로 결정됩니다.

또한 패키지는 모든 레코드를 올바른 순서로 가져오는 쿼리 범위를 제공합니다.

Spatie는 벨기에 앤트워프에 위치한 웹디자인 에이전시입니다. 당사 웹사이트에서 당사의 모든 오픈 소스 프로젝트에 대한 개요를 확인할 수 있습니다.

우리를 지원하세요

프리미엄 비디오 과정을 시청하여 이와 같은 패키지를 만드는 방법을 알아보세요.

우리는 동급 최고의 오픈 소스 패키지를 만드는 데 많은 리소스를 투자합니다. 유료 제품 중 하나를 구매하여 우리를 지원할 수 있습니다.

귀하가 사용하고 있는 당사 패키지를 언급하면서 귀하의 고향에서 엽서를 보내주셔서 진심으로 감사드립니다. 연락처 페이지에서 주소를 확인하실 수 있습니다. 우리는 수신된 모든 엽서를 가상 엽서 월에 게시합니다.

설치

Laravel 6.x 또는 PHP 7.x의 경우 이 패키지의 버전 3.x를 사용하세요.

이 패키지는 Composer를 통해 설치할 수 있습니다.

 composer require spatie/eloquent-sortable

Laravel 5.5 이상에서는 서비스 제공자가 자동으로 등록됩니다. 이전 버전의 프레임워크에서는 config/app.php 파일에 서비스 공급자를 추가하기만 하면 됩니다.

 ' providers ' => [
    ...
    Spatie  EloquentSortable EloquentSortableServiceProvider::class,
];

선택적으로 다음을 사용하여 구성 파일을 게시할 수 있습니다.

php artisan vendor:publish --tag=eloquent-sortable-config

이것은 config/eloquent-sortable.php 에 게시될 파일의 ​​내용입니다.

 return [
  /*
   * The name of the column that will be used to sort models.
   */
  ' order_column_name ' => ' order_column ' ,

  /*
   * Define if the models should sort when creating. When true, the package
   * will automatically assign the highest order number to a new model
   */
  ' sort_when_creating ' => true ,

  /*
   * Define if the timestamps should be ignored when sorting.
   * When true, updated_at will not be updated when using setNewOrder
   */
  ' ignore_timestamps ' => false ,
];

용법

모델에 정렬 가능한 동작을 추가하려면 다음을 수행해야 합니다.

1. SpatieEloquentSortableSortable 인터페이스를 구현합니다.
2. SpatieEloquentSortableSortableTrait 특성을 사용하세요.
3. 선택적으로 주문 열로 사용할 열을 지정합니다. 기본값은 order_column 입니다.

예

 use Spatie  EloquentSortable  Sortable ;
use Spatie  EloquentSortable  SortableTrait ;

class MyModel extends Model implements Sortable
{
    use SortableTrait;

    public $ sortable = [
        ' order_column_name ' => ' order_column ' ,
        ' sort_when_creating ' => true ,
    ];

    // ...
}

$sortable['order_column_name'] 값을 설정하지 않으면 패키지는 주문 열 이름이 order_column 으로 지정된다고 가정합니다.

$sortable['sort_when_creating'] 값을 설정하지 않으면 패키지는 자동으로 가장 높은 주문 번호를 새 모델에 할당합니다.

MyModel 의 db 테이블이 비어 있다고 가정합니다.

 $ myModel = new MyModel ();
$ myModel -> save (); // order_column for this record will be set to 1

$ myModel = new MyModel ();
$ myModel -> save (); // order_column for this record will be set to 2

$ myModel = new MyModel ();
$ myModel -> save (); // order_column for this record will be set to 3


//the trait also provides the ordered query scope
$ orderedRecords = MyModel:: ordered ()-> get ();

setNewOrder -메서드를 사용하여 모든 레코드에 대해 새 순서를 설정할 수 있습니다.

 /**
 * the record for model id 3 will have order_column value 1
 * the record for model id 1 will have order_column value 2
 * the record for model id 2 will have order_column value 3
 */
MyModel:: setNewOrder ([ 3 , 1 , 2 ]);

선택적으로 시작 주문 번호를 두 번째 인수로 전달할 수 있습니다.

 /**
 * the record for model id 3 will have order_column value 11
 * the record for model id 1 will have order_column value 12
 * the record for model id 2 will have order_column value 13
 */
MyModel:: setNewOrder ([ 3 , 1 , 2 ], 10 );

클로저를 네 번째 인수로 전달하여 실행될 쿼리를 수정할 수 있습니다.

 /**
 * the record for model id 3 will have order_column value 11
 * the record for model id 1 will have order_column value 12
 * the record for model id 2 will have order_column value 13
 */
MyModel:: setNewOrder ([ 3 , 1 , 2 ], 10 , null , function ( $ query ) {
    $ query -> withoutGlobalScope ( new ActiveScope );
});

기본 키가 아닌 열을 사용하여 정렬하려면 setNewOrderByCustomColumn -메서드를 사용하세요.

 /**
 * the record for model uuid '7a051131-d387-4276-bfda-e7c376099715' will have order_column value 1
 * the record for model uuid '40324562-c7ca-4c69-8018-aff81bff8c95' will have order_column value 2
 * the record for model uuid '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1' will have order_column value 3
 */
MyModel:: setNewOrderByCustomColumn ( ' uuid ' , [
   ' 7a051131-d387-4276-bfda-e7c376099715 ' ,
   ' 40324562-c7ca-4c69-8018-aff81bff8c95 ' ,
   ' 5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1 '
]);

setNewOrder 와 마찬가지로 setNewOrderByCustomColumn 도 선택적 시작 순서 인수를 허용합니다.

 /**
 * the record for model uuid '7a051131-d387-4276-bfda-e7c376099715' will have order_column value 10
 * the record for model uuid '40324562-c7ca-4c69-8018-aff81bff8c95' will have order_column value 11
 * the record for model uuid '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1' will have order_column value 12
 */
MyModel:: setNewOrderByCustomColumn ( ' uuid ' , [
   ' 7a051131-d387-4276-bfda-e7c376099715 ' ,
   ' 40324562-c7ca-4c69-8018-aff81bff8c95 ' ,
   ' 5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1 '
], 10 );

다음 방법을 사용하여 모델을 위나 아래로 이동할 수도 있습니다.

 $ myModel -> moveOrderDown ();
$ myModel -> moveOrderUp ();

모델을 첫 번째 또는 마지막 위치로 이동할 수도 있습니다.

 $ myModel -> moveToStart ();
$ myModel -> moveToEnd ();

요소가 순서대로 첫 번째인지 마지막인지 확인할 수 있습니다.

 $ myModel -> isFirstInOrder ();
$ myModel -> isLastInOrder ();

두 모델의 순서를 바꿀 수 있습니다:

MyModel:: swapOrder ( $ myModel , $ anotherModel );

그룹화

모델/테이블에 그룹화 필드(일반적으로 외래 키)( id, user_id , title, order_column 가 있고 위 메서드를 고려하려는 경우 모델에서 buildSortQuery 메서드를 만들 수 있습니다.

 // MyModel.php

public function buildSortQuery ()
{
    return static :: query ()-> where ( ' user_id ' , $ this -> user_id );
}

이렇게 하면 계산이 모델 인스턴스의 필드 값으로 제한됩니다.

전달된 이벤트

정렬이 완료되면 수신할 수 있는 이벤트( SpatieEloquentSortableEloquentModelSortedEvent )가 전달됩니다. 이는 캐시 지우기 또는 정렬 후 수행해야 하는 기타 작업과 같은 정렬 후 논리를 실행하는 데 유용할 수 있습니다.

이벤트에는 정렬된 Eloquent 클래스를 편리하게 확인할 수 있는 isFor 도우미가 있습니다.

다음은 이 이벤트를 수신하는 방법의 예입니다.

 use Spatie  EloquentSortable  EloquentModelSortedEvent as SortEvent ;

class SortingListener
{
    public function handle ( SortEvent $ event ): void {
        if ( $ event -> isFor (MyClass::class)) {
            // ToDo: flush our cache
        }
    }
}

테스트

패키지에는 Orchestra로 설정된 일부 통합/스모크 테스트가 포함되어 있습니다. 테스트는 phpunit을 통해 실행할 수 있습니다.

vendor/bin/phpunit

변경 내역

최근 변경된 사항에 대한 자세한 내용은 변경 로그를 참조하세요.

기여

자세한 내용은 CONTRIBUTING을 참조하세요.

보안 취약점

보안 취약점을 보고하는 방법에 대한 보안 정책을 검토하세요.

크레딧

• 프리크 반 데르 헤르텐
• 모든 기여자

대안

• 리스티파이
• 루토리케 정렬 가능

특허

MIT 라이센스(MIT). 자세한 내용은 라이센스 파일을 참조하십시오.