v7.0.0-beta.2 release

This commit is contained in:
HeuJung committed 2026-04-20 20:37:49 +09:00
1 parent 6595fd0eb5
commit fa8eba7a0d
1165 files changed
+107118 -762127

No files matched your search

+180
View File
@@ -0,0 +1,180 @@
<?php
namespace App\Models\Concerns;
use Illuminate\Database\Eloquent\Model;
/**
* HasUserOverrides Trait.
*
* 모델에 user_overrides 필드 자동 관리 기능을 추가합니다.
*
* 사용법:
* ```php
* class NotificationTemplate extends Model {
* use HasUserOverrides;
*
* protected array $trackableFields = ['subject', 'body', 'is_active'];
* }
* ```
*
* 동작:
* - 사용자가 trackable 필드를 수정 → user_overrides 에 자동 기록
* - 사용자 경로가 Eloquent 인스턴스 `->update()`, `->save()` 또는 mass update
* `Model::where(...)->update()` 중 어느 것이든 **모두 자동 추적**
* (mass update 는 커스텀 Builder 가 per-row 로 분해하여 `updating` 이벤트 발화)
* - 시더/업그레이드 스텝에서 syncFromUpgrade() 호출 → 기록된 필드 보존
*
* 컨테이너 플래그 `user_overrides.seeding` 으로 시더/사용자 컨텍스트를 구분합니다.
*
* 대량 처리(수천~수만 행) 가 필요해 이벤트 발화 비용을 피하려면
* `DB::table('...')->update(...)` (Eloquent 우회) 사용을 권장합니다.
*
* @since 7.0.0-beta.2
*/
trait HasUserOverrides
{
/**
* 커스텀 Eloquent Builder 반환 — mass update 시에도 user_overrides 자동 기록.
*
* @param \Illuminate\Database\Query\Builder $query
* @return UserOverridesAwareBuilder
*/
public function newEloquentBuilder($query): UserOverridesAwareBuilder
{
return new UserOverridesAwareBuilder($query);
}
/**
* trait 부팅 — Eloquent updating 이벤트로 사용자 수정 자동 기록.
*/
public static function bootHasUserOverrides(): void
{
static::updating(function (Model $model) {
if (app()->bound('user_overrides.seeding') && app('user_overrides.seeding') === true) {
return;
}
$userOverrides = $model->user_overrides ?? [];
$original = $userOverrides;
foreach ($model->getTrackableFields() as $field) {
if ($model->isDirty($field) && ! in_array($field, $userOverrides, true)) {
$userOverrides[] = $field;
}
}
if ($userOverrides !== $original) {
$model->user_overrides = $userOverrides;
}
});
}
/**
* trackable 필드 목록을 반환합니다.
*
* 모델에서 `protected array $trackableFields = [...]` 로 오버라이드할 수 있습니다.
*
* @return array<int, string>
*/
public function getTrackableFields(): array
{
return property_exists($this, 'trackableFields') ? $this->trackableFields : [];
}
/**
* 현재 모델 상태와 신규 입력 값을 비교하여 user_overrides 에 추가될 필드 집합을 계산합니다.
*
* `UserOverridesAwareBuilder` 가 mass update 시에도 user_overrides 를 누적하도록
* 호출합니다. Eloquent save/event 경로를 우회하여도 동일한 로직을 재사용할 수 있도록
* 공개 메서드로 노출합니다.
*
* @param array<string, mixed> $incomingAttributes 사용자 입력/mass update 값
* @return array<int, string> 계산된 user_overrides 배열
*/
public function calculateUserOverridesFor(array $incomingAttributes): array
{
$current = $this->user_overrides ?? [];
foreach ($this->getTrackableFields() as $field) {
if (! array_key_exists($field, $incomingAttributes)) {
continue;
}
$incoming = $incomingAttributes[$field];
if ($this->{$field} != $incoming && ! in_array($field, $current, true)) {
$current[] = $field;
}
}
return $current;
}
/**
* 업그레이드 스텝/시더에서 호출 — user_overrides 보존하며 갱신합니다.
*
* trackable 필드 + user_overrides 에 등록된 필드는 갱신을 건너뜁니다.
*
* @param array<string, mixed> $newAttributes 시더 정의 값
*/
public function syncFromUpgrade(array $newAttributes): void
{
$userOverrides = $this->user_overrides ?? [];
$trackable = $this->getTrackableFields();
$updateData = [];
foreach ($newAttributes as $field => $value) {
if (in_array($field, $trackable, true) && in_array($field, $userOverrides, true)) {
continue;
}
$updateData[$field] = $value;
}
if (empty($updateData)) {
return;
}
app()->instance('user_overrides.seeding', true);
try {
$this->update($updateData);
} finally {
app()->forgetInstance('user_overrides.seeding');
}
}
/**
* 시더 컨텍스트에서 신규 생성 — user_overrides 자동 기록 비활성.
*
* @param array<string, mixed> $attributes 신규 생성 속성
* @return static 생성된 모델 인스턴스
*/
public static function createFromUpgrade(array $attributes): self
{
app()->instance('user_overrides.seeding', true);
try {
return static::create(array_merge(
$attributes,
['user_overrides' => null],
));
} finally {
app()->forgetInstance('user_overrides.seeding');
}
}
/**
* 시더 헬퍼 — 존재하지 않으면 생성, 존재하면 syncFromUpgrade 호출합니다.
*
* @param array<string, mixed> $finder updateOrCreate 의 첫 번째 인자
* @param array<string, mixed> $attributes 시더 정의 값
* @return static 생성/갱신된 모델 인스턴스
*/
public static function syncOrCreateFromUpgrade(array $finder, array $attributes): self
{
$existing = static::where($finder)->first();
if (! $existing) {
return static::createFromUpgrade(array_merge($finder, $attributes));
}
$existing->syncFromUpgrade($attributes);
return $existing;
}
}
@@ -5,16 +5,17 @@ namespace App\Models\Concerns;
use Illuminate\Database\Eloquent\Builder;
/**
* 메일 템플릿 모델 공통 Trait.
* 알림 템플릿 컨텐츠 Trait.
*
* 코어/모듈 메일 템플릿 모델에서 공통으로 사용하는 casts, 스코프, 헬퍼를 제공합니다.
* NotificationTemplate 모델에서 공통으로 사용하는 casts, 스코프, 다국어 헬퍼,
* 변수 치환 메서드를 제공합니다.
*/
trait MailTemplateBehavior
trait NotificationContentBehavior
{
/**
* 공통 casts를 초기화합니다.
*/
public function initializeMailTemplateBehavior(): void
public function initializeNotificationContentBehavior(): void
{
$this->mergeCasts([
'subject' => 'array',
@@ -100,4 +101,25 @@ trait MailTemplateBehavior
'body' => strtr($body, $replacements),
];
}
/**
* 단일 문자열의 변수를 치환합니다.
*
* click_url 등 다국어가 아닌 단일 문자열에 {key} 패턴을 치환합니다.
*
* @param string $template 치환 대상 문자열 (예: /mypage/orders/{order_number})
* @param array $data 변수 데이터
* @return string 치환된 문자열
*/
public function replaceVariablesInString(string $template, array $data): string
{
$replacements = [];
foreach ($data as $key => $value) {
if (is_string($value) || is_numeric($value)) {
$replacements['{' . $key . '}'] = (string) $value;
}
}
return strtr($template, $replacements);
}
}
@@ -0,0 +1,103 @@
<?php
namespace App\Models\Concerns;
use Illuminate\Database\Eloquent\Builder;
/**
* user_overrides 인지 Eloquent Builder.
*
* `HasUserOverrides` trait 이 적용된 모델의 mass update 를 가로채 user_overrides
* 컬럼에 수정 필드를 자동 누적합니다.
*
* 동작 흐름:
* - `Model::where(...)->update([...])` 호출 시
* - 대상 행을 preload (1 SELECT)
* - 각 행별로 `calculateUserOverridesFor($values)` 호출하여 user_overrides 계산
* - per-row UPDATE 를 parent::update() 로 수행 (재귀 없이)
* - 시더 컨텍스트(`user_overrides.seeding`) 에서는 기본 경로 유지
* - 입력 $values 에 trackable 필드가 하나도 없으면 계산 건너뛰고 기본 경로 (성능 최적화)
*
* 성능 트레이드오프:
* - 기본: 1 UPDATE
* - 추적 활성: 1 SELECT + N UPDATE (trackable 필드 포함 시에만)
* - 관리자 UI 일괄 저장(수십 행 이하) 대상에는 차이 무시 가능.
* - 대량 처리는 `DB::table()->update()` (Eloquent 우회) 권장.
*
* @since 7.0.0-beta.2
*/
class UserOverridesAwareBuilder extends Builder
{
/**
* 쿼리 조건에 부합하는 모델을 업데이트합니다.
*
* @param array<string, mixed> $values
* @return int 영향받은 행 수
*/
public function update(array $values)
{
// 시더 컨텍스트에서는 trait 이벤트 handler 가 어차피 early return 하므로
// 성능을 위해 기본 mass update 경로 사용.
if (app()->bound('user_overrides.seeding') && app('user_overrides.seeding') === true) {
return parent::update($values);
}
$model = $this->getModel();
$trackable = method_exists($model, 'getTrackableFields')
? $model->getTrackableFields()
: [];
// 입력에 trackable 필드가 하나도 없으면 user_overrides 갱신 불필요 — 기본 경로.
if (empty($trackable) || empty(array_intersect(array_keys($values), $trackable))) {
return parent::update($values);
}
$models = $this->get();
if ($models->isEmpty()) {
return 0;
}
$affected = 0;
$keyName = $model->getKeyName();
foreach ($models as $row) {
$newOverrides = $row->calculateUserOverridesFor($values);
$rowValues = $values;
// user_overrides 에 변경이 있으면 UPDATE payload 에 포함 (json cast 는 Eloquent 가 처리)
if ($newOverrides !== ($row->user_overrides ?? [])) {
$rowValues['user_overrides'] = $newOverrides;
}
// 재귀 없이 기본 UPDATE — PK 단일 행 UPDATE
$affected += $row->newQueryWithoutScopes()
->where($keyName, $row->getKey())
->toBase()
->update($this->prepareValuesForRow($rowValues, $row));
}
return $affected;
}
/**
* array-cast 필드를 DB 저장 형식(JSON 문자열)으로 변환합니다.
*
* Eloquent Builder::update 는 toBase() 로 진입 시 array 값을 자동 JSON 인코딩하지
* 않으므로, 본 메서드에서 모델의 cast 설정을 참조하여 사전 변환합니다.
*
* @param array<string, mixed> $values
* @param \Illuminate\Database\Eloquent\Model $model
* @return array<string, mixed>
*/
private function prepareValuesForRow(array $values, $model): array
{
foreach ($values as $key => $value) {
if (is_array($value) || is_object($value)) {
// array/json cast 필드는 JSON 인코딩 후 저장
$values[$key] = json_encode($value);
}
}
return $values;
}
}