Application Classes

Antes de escribir una clase, decide dónde va el código siguiendo este orden y deteniéndote en la primera coincidencia:

1. Package — el código pertenece a un dominio que se está aislando (p. ej. billing), así que vive en el paquete junto con todo lo que ese dominio necesita.
2. Modelo — el código trata sobre un registro, o sobre los registros almacenados para él. $user->markLoggedIn(), User::emailExists($email), $plan->can_be_deleted.
3. Servicio — el código se comunica con un sistema externo: un proveedor de pagos, una API, una pasarela SMS, una búsqueda de geolocalización. Consulta el estándar de Services.
4. Helper — el código es una función pura que solo transforma sus argumentos, y más de un lugar la necesita. Consulta "Las utilidades compartidas van en Helpers" en el estándar de PHP.
5. Componente Livewire, middleware, observer o job — el código es el punto de entrada que recibe la solicitud o reacciona a un evento, y el trabajo es lo bastante pequeño como para leerse ahí.
6. Action — una única operación síncrona que debe devolver su resultado al llamador. Una clase por operación, en app/Actions/ para la aplicación anfitriona o src/Actions/ dentro de un paquete, con un método handle() que devuelve el resultado; se ejecuta en proceso y devuelve un valor, a diferencia de un job, que puede encolarse.
7. Clase de aplicación en app/Classes/ — nada de lo anterior encaja, y el código tiene un propósito propio que merece nombre.

Una clase de aplicación es para lógica que pertenece a la aplicación pero no a un único registro, y que no alcanza ningún sistema externo: un objeto de valor, un cálculo de dominio que abarca varios modelos, un motor o un flujo controlado desde un middleware donde no hay ningún componente Livewire para contenerlo.

// Correct — the referral program owns capturing a code and registering the referral
App\Classes\Referrals

// Correct — plan limits are a domain calculation that no single model owns
App\Classes\PlanLimits

// Incorrect — this is a question about stored users, so it belongs on the model
App\Classes\UserEmailChecker

Un paquete aísla todo el código relacionado con un dominio. El paquete puede usar clases del host (app/).
El host no debe contener la lógica del paquete: solo hace de puente a través de traits y helpers que delegan y devuelven null/vacío cuando el paquete está desactivado o ausente.
El host no debe referenciar el namespace del paquete directamente fuera de los helpers de guardia.

Mover un método a un model se justifica cuando el model es el propietario correcto, no cuando la clase actual se siente grande. Un método con un único llamador puede quedarse en la clase de aplicación que posee el flujo.
A la inversa, un método usado desde varios lugares tampoco pasa automáticamente a ser material del model: aplica el orden anterior y pregúntate de qué trata el código, no con qué frecuencia se ejecuta.
Cuando el registro es el propietario, el model nombra la acción y la clase conserva la mecánica: $user->recordPaidSubscriptionReward(...) expone el vocabulario en el model y delega en la clase de aplicación que posee el flujo de referidos.

Una acción es una única operación síncrona que debe devolver su resultado a quien la llama: un true/false, un registro, un DTO. Se parece a un job, pero se ejecuta en el proceso y devuelve un valor; conviértela en un job solo cuando el trabajo pueda encolarse.
Una clase por operación, en app/Actions/ para la aplicación host o en src/Actions/ dentro de un package, con un método handle() que devuelva el resultado:

// Correct — one operation, returns the outcome to the caller
$ok = app(RecordSubscriptionReward::class)->handle($user, $amount, $currency, $invoiceId);

// Incorrect — a job used only to get a return value
dispatch(new RecordSubscriptionReward($user, $amount));

Una clase de aplicación es diferente: mantiene la lógica y el estado de un dominio — propiedades y varios métodos que le dan servicio, como App\Classes\Referrals. Una acción realiza una sola cosa; una clase gestiona un flujo.