Execution Attributes and Configuration

Purpose and Scope

This document covers the ManagesAttributes trait and the configuration methods it provides for controlling event execution behavior. These attributes define when, where, and how scheduled events run, independent of their timing schedule.

For information about defining when events run based on time schedules (cron expressions), see Defining Schedule Frequencies. For detailed information about concurrency control mechanisms, see Concurrency and Mutex Management.

Sources: src/Scheduling/ManagesAttributes.php1-186

---

Overview

The ManagesAttributes trait is used by the Event class to provide a fluent API for configuring execution behavior. It defines properties that control environment restrictions, user context, maintenance mode behavior, overlap prevention, background execution, and conditional filters.

Diagram: ManagesAttributes Structure

Sources: src/Scheduling/Event.php35-41 src/Scheduling/ManagesAttributes.php11-76

---

Attribute Properties

The trait defines the following properties that control event behavior:

Property	Type	Default	Purpose
$expression	string	'* * * * *'	Cron expression for scheduling
$repeatSeconds	?int	null	Sub-minute repetition interval
$timezone	DateTimeZone|string|null	null	Timezone for schedule evaluation
$user	?string	null	User context for command execution
$environments	array	[]	Allowed execution environments
$evenInMaintenanceMode	bool	false	Run during maintenance mode
$withoutOverlapping	bool	false	Prevent concurrent executions
$onOneServer	bool	false	Single-server execution mode
$expiresAt	int	1440	Mutex expiration time (minutes)
$runInBackground	bool	false	Background execution mode
$filters	array	[]	Inclusion filter callbacks
$rejects	array	[]	Exclusion filter callbacks
$description	?string	null	Human-readable event name

Sources: src/Scheduling/ManagesAttributes.php13-76

---

Environment and Context Configuration

Environment Restrictions

The environments() method limits which application environments can execute the event. This is evaluated in the runsInEnvironment() method.

Diagram: Environment Evaluation Flow

Usage:

The method accepts either an array or variadic arguments. An empty $environments array allows execution in all environments.

Sources: src/Scheduling/ManagesAttributes.php88-98 src/Scheduling/Event.php282-287

Maintenance Mode Behavior

By default, scheduled events do not run when the application is in maintenance mode. The evenInMaintenanceMode() method overrides this behavior:

The runsInMaintenanceMode() method checks the $evenInMaintenanceMode property. During event eligibility evaluation in isDue(), events that don't explicitly allow maintenance mode are skipped.

Sources: src/Scheduling/ManagesAttributes.php100-108 src/Scheduling/Event.php249-255 src/Scheduling/Event.php259-263

User Context

The user() method sets the user context under which system commands should execute. This property is stored but its implementation for actually executing commands under a different user would be handled by the process execution layer:

Note: This attribute is defined but not actively used in the current implementation for command execution.

Sources: src/Scheduling/ManagesAttributes.php79-86

---

Execution Mode Configuration

Background Execution

The runInBackground() method configures events to execute asynchronously in the background rather than blocking the scheduler loop:

When $runInBackground is true, the ScheduleRunCommand adds the event to a concurrent coroutine pool instead of executing it synchronously. This is particularly important for long-running tasks that should not block other scheduled events.

Diagram: Background vs Foreground Execution

Sources: src/Scheduling/ManagesAttributes.php135-143

Overlap Prevention

The withoutOverlapping() method prevents multiple instances of the same event from running concurrently:

The method accepts an optional expiration time in minutes (default: 1440 = 24 hours). It sets $withoutOverlapping = true and adds a skip() filter that checks if a mutex exists. For detailed mutex mechanics, see Concurrency and Mutex Management.

Sources: src/Scheduling/ManagesAttributes.php110-123 src/Scheduling/Event.php129-133

Single-Server Execution

The onOneServer() method ensures that in multi-server deployments, only one server executes the event:

This sets the $onOneServer property to true. The actual coordination is handled by the Schedule class using the SchedulingMutex contract. See Concurrency and Mutex Management for implementation details.

Sources: src/Scheduling/ManagesAttributes.php125-133

---

Conditional Execution Filters

The trait provides two methods for conditional execution: when() and skip(). These add callbacks to the $filters and $rejects arrays respectively, which are evaluated during the filtersPass() method.

Filter Evaluation Flow

Diagram: Filter Evaluation Sequence

Sources: src/Scheduling/Event.php291-309

When Method (Inclusion Filters)

The when() method registers a callback that must return true for the event to execute. Multiple when() calls create an AND condition - all must pass:

The method accepts either a boolean value or a Closure. Boolean values are wrapped in a closure that returns the value.

Sources: src/Scheduling/ManagesAttributes.php145-155

Skip Method (Exclusion Filters)

The skip() method registers a callback that must return false for the event to execute. If the callback returns true, the event is skipped:

Like when(), it accepts either a boolean or closure.

Sources: src/Scheduling/ManagesAttributes.php157-167

Filter Callback Resolution

Both when() and skip() use Reflector::isCallable() to determine if the value is a callback or a static boolean. The callbacks are executed with dependency injection via the container's call() method, allowing type-hinted dependencies.

Sources: src/Scheduling/ManagesAttributes.php148-153 src/Scheduling/ManagesAttributes.php160-165 src/Scheduling/Event.php296-306

---

Event Metadata

Description and Name

The description() and name() methods set a human-readable description for the event. Both methods set the same $description property:

The description is used in:

• getSummaryForDisplay() for command output
• Email subjects when using emailOutputTo()
• The schedule:list command output

If no description is set, the command string is used as a fallback.

Sources: src/Scheduling/ManagesAttributes.php169-185 src/Scheduling/Event.php665-673 src/Scheduling/Event.php444-453

---

Attribute Evaluation During Execution

The following diagram shows how attributes are evaluated during the event lifecycle:

Diagram: Attribute Evaluation Flow

Sources: src/Scheduling/Event.php247-255 src/Scheduling/Event.php291-309 src/Scheduling/Event.php129-133

---

Configuration Method Chaining

All configuration methods return static, enabling fluent method chaining:

The methods from ManagesAttributes, ManagesFrequencies, and Event can be chained together in any order to configure the complete event behavior.

Sources: src/Scheduling/ManagesAttributes.php81-185

---

Summary Table

Method	Property Set	Effect on Execution
user(string)	$user	Sets user context (not actively enforced)
environments(...$envs)	$environments	Restricts to specific environments via runsInEnvironment()
evenInMaintenanceMode()	$evenInMaintenanceMode	Allows execution during maintenance mode
withoutOverlapping(int)	$withoutOverlapping, $expiresAt	Adds mutex check to $rejects filters
onOneServer()	$onOneServer	Enables single-server coordination in Schedule
runInBackground()	$runInBackground	Executes in coroutine pool instead of blocking
when(bool|Closure)	$filters	Adds inclusion condition
skip(bool|Closure)	$rejects	Adds exclusion condition
name(string)	$description	Sets human-readable description
description(string)	$description	Sets human-readable description

Sources: src/Scheduling/ManagesAttributes.php11-186