Facades and Global Helper Functions

Purpose and Scope

This page documents Hypervel's facade pattern implementation and the global helper functions that provide convenient access to framework features. Facades offer a static interface to services registered in the dependency injection container, while global helper functions provide procedural-style shortcuts for common operations.

For information about the underlying dependency injection container, see Application Container and Lifecycle. For service registration through providers, see Service Providers and Bootstrapping.

---

Facade Architecture

Hypervel implements the facade pattern to provide static access to services bound in the container. Facades act as proxies that forward static method calls to the underlying service instance.

Sources: src/support/src/Facades/URL.php1-49

Facade Resolution Process

When a static method is called on a facade:

1. PHP's __callStatic() magic method intercepts the call
2. The facade calls getFacadeAccessor() to determine the service binding key
3. The service instance is resolved from the container using ApplicationContext::getContainer()
4. The method is invoked on the resolved instance
5. The result is returned to the caller

---

Available Facades

URL Facade

The URL facade provides static access to the UrlGenerator service for generating application URLs.

Method	Description
route()	Generate URL to named route
to()	Generate application URL
query()	Generate URL with query parameters
secure()	Generate secure (HTTPS) URL
asset()	Generate asset URL
signedRoute()	Generate signed route URL
temporarySignedRoute()	Generate temporary signed URL
hasValidSignature()	Validate signed request
full()	Get full current URL
current()	Get current URL without query
previous()	Get previous URL
forceScheme()	Force URL scheme
forceHttps()	Force HTTPS for URLs
useOrigin()	Set URL origin for multi-tenancy

Sources: src/support/src/Facades/URL.php9-48 src/router/src/Contracts/UrlGenerator.php14-151

---

Global Helper Functions

Hypervel provides over 60 global helper functions organized by functional area. These functions are defined with existence checks (if (! function_exists())) to allow user overrides.

Helper Function Categories

Sources: src/foundation/src/helpers.php1-815

---

Application and Container Helpers

app()

Resolves services from the dependency injection container. When called without arguments, returns the container itself.

Key behaviors:

• Returns Application instance when called with no arguments
• Resolves services from container using ApplicationContext::getContainer()
• Supports instantiation with parameters via make()
• Falls back to direct instantiation when no container is available

Sources: src/foundation/src/helpers.php347-380

resolve()

Alias for app() that emphasizes service resolution from the container.

Sources: src/foundation/src/helpers.php510-524

---

Path Helpers

Path helpers generate absolute filesystem paths to standard application directories. Each helper checks for container availability and falls back to the BASE_PATH constant if necessary.

Sources: src/foundation/src/helpers.php99-229

Available Path Helpers

Function	Directory	Example
base_path()	Application root	/var/www/app
app_path()	Application code	/var/www/app/app
database_path()	Database files	/var/www/app/database
storage_path()	Storage directory	/var/www/app/storage
config_path()	Configuration files	/var/www/app/config
resource_path()	Resources	/var/www/app/resources
lang_path()	Language files	/var/www/app/lang
public_path()	Public assets	/var/www/app/public

Sources: src/foundation/src/helpers.php99-229

---

HTTP and Response Helpers

abort()

Throws HTTP exceptions to terminate request processing with a specific status code.

Supported exception types:

• Accepts Responsable objects for custom responses
• Throws NotFoundHttpException for 404 errors
• Throws HttpException for other status codes
• Throws HttpResponseException for Responsable objects

Sources: src/foundation/src/helpers.php41-59

abort_if() and abort_unless()

Conditional abort helpers that throw exceptions based on boolean conditions.

Sources: src/foundation/src/helpers.php61-97

request()

Retrieves the current HTTP request or extracts input values from it.

Behavior modes:

• No arguments: Returns RequestContract instance
• String key: Returns single input value
• Array of keys: Returns array of input values

Sources: src/foundation/src/helpers.php526-548

response()

Creates HTTP responses with specified content, status, and headers.

Sources: src/foundation/src/helpers.php550-566

redirect()

Creates redirect responses to specified URLs.

Sources: src/foundation/src/helpers.php568-577

to_route()

Creates redirect responses to named routes with parameters.

Sources: src/foundation/src/helpers.php579-594

---

URL Generation Helpers

URL generation helpers provide convenient access to the UrlGenerator service. These functions are defined in two locations: the foundation helpers file and the router package functions file.

Sources: src/router/src/Functions.php1-49 src/foundation/src/helpers.php680-720

route()

Generates URLs to named routes with parameter substitution.

Parameters:

• $name: Route name registered via Route::get()->name()
• $parameters: Route parameters and query string values
• $absolute: Generate absolute or relative URL
• $server: Server type ('http', 'ws', etc.)

Sources: src/router/src/Functions.php12-19 src/foundation/src/helpers.php680-690

url()

Generates application URLs with optional path segments and security settings.

Behavior:

• No arguments: Returns UrlGenerator instance
• With path: Generates absolute URL with path and extra segments
• Validates and preserves already-valid URLs (http://, https://, mailto:, etc.)

Sources: src/router/src/Functions.php21-32 src/foundation/src/helpers.php692-700

secure_url()

Generates secure (HTTPS) URLs to the specified path.

Sources: src/router/src/Functions.php34-40 src/foundation/src/helpers.php702-710

asset()

Generates URLs to application assets (CSS, JavaScript, images).

Behavior:

• Returns path unchanged if already a valid URL
• Appends path to application root URL
• Respects forced URL schemes and origins

Sources: src/router/src/Functions.php42-48 src/foundation/src/helpers.php712-720

---

Configuration and Cache Helpers

config()

Retrieves or sets configuration values. Delegates to the configuration package's config() function.

Behavior modes:

• No arguments: Returns Repository instance
• String key: Returns configuration value (e.g., 'app.name')
• Array: Sets multiple configuration values

Sources: src/foundation/src/helpers.php274-287

cache()

Accesses cached values or stores new cache entries. Delegates to the cache package's cache() function.

Behavior modes:

• No arguments: Returns CacheManager instance
• String key: Retrieves cached value
• Array: Stores values with expiration (e.g., ['key' => 'value'], 3600)

Sources: src/foundation/src/helpers.php289-305

---

Authentication and Security Helpers

auth()

Retrieves authentication guard instances. Delegates to the auth package's auth() function.

Sources: src/foundation/src/helpers.php722-732

bcrypt()

Hashes passwords using the bcrypt algorithm.

Sources: src/foundation/src/helpers.php231-240

encrypt() and decrypt()

Encrypts and decrypts values using the application's encrypter service.

Sources: src/foundation/src/helpers.php242-262

cookie()

Creates cookie instances or retrieves the cookie manager.

Sources: src/foundation/src/helpers.php307-323

csrf_token() and csrf_field()

Generates CSRF tokens and form fields. Delegates to session package functions.

Sources: src/foundation/src/helpers.php325-345

policy()

Retrieves authorization policy instances for given classes.

Sources: src/foundation/src/helpers.php497-508

---

View and Translation Helpers

view()

Creates view instances or retrieves the view factory.

Behavior:

• No arguments: Returns FactoryContract instance
• With view name: Returns compiled view instance with data

Sources: src/foundation/src/helpers.php766-783

trans() and __()

Translates text using the translation system.

Sources: src/foundation/src/helpers.php734-764

trans_choice()

Translates text with pluralization based on count.

Sources: src/foundation/src/helpers.php746-754

method_field()

Generates hidden form field for HTTP method spoofing.

Sources: src/foundation/src/helpers.php264-272 src/foundation/src/helpers.php785-793

---

Event and Job Helpers

event()

Dispatches events to registered listeners. Delegates to the event package's event() function.

Sources: src/foundation/src/helpers.php407-421

broadcast()

Initiates event broadcasting to real-time channels.

Returns: PendingBroadcast instance for configuring broadcast channels and recipients.

Sources: src/foundation/src/helpers.php125-133

dispatch()

Dispatches jobs to the queue system.

Behavior:

• Closure jobs: Returns PendingClosureDispatch
• Object jobs: Returns PendingDispatch

Sources: src/foundation/src/helpers.php382-393

dispatch_sync()

Dispatches jobs synchronously in the current process.

Sources: src/foundation/src/helpers.php395-405

---

Utility Helpers

logger()

Retrieves logger instance or logs debug messages.

Behavior:

• No arguments: Returns LoggerInterface instance
• With message: Logs message at debug level and returns null

Sources: src/foundation/src/helpers.php456-473

info()

Logs informational messages with optional backtrace.

Sources: src/foundation/src/helpers.php441-454

report()

Reports exceptions to the exception handler without halting execution.

Sources: src/foundation/src/helpers.php596-608

rescue()

Executes callbacks with exception handling and fallback values.

Behavior:

• Executes $callback
• On exception: Reports if $report is true, returns $rescue value
• Returns callback result on success

Sources: src/foundation/src/helpers.php610-634

now() and today()

Creates Carbon date/time instances.

Sources: src/foundation/src/helpers.php487-495 src/foundation/src/helpers.php650-660

validator()

Creates validator instances for input validation.

Sources: src/foundation/src/helpers.php662-678

session()

Accesses session values or retrieves the session instance. Delegates to the session package's session() function.

Sources: src/foundation/src/helpers.php636-648

fake()

Retrieves Faker generator instances for fake data generation.

Behavior:

• Uses configured faker locale from app.faker_locale
• Caches generator instances per locale
• Only available when faker/faker package is installed

Sources: src/foundation/src/helpers.php423-439

mix()

Retrieves versioned Mix file paths from the manifest.

Sources: src/foundation/src/helpers.php475-485

---

Coroutine Helpers

Hypervel provides helpers for Swoole's coroutine functionality, enabling concurrent execution in the coroutine context.

Sources: src/foundation/src/helpers.php795-814

go() and co()

Creates new coroutines for concurrent execution. Both are aliases for the same coroutine creation functionality.

Returns: Coroutine ID on success, false on failure.

Sources: src/foundation/src/helpers.php795-807

defer()

Registers deferred callbacks that execute when the current coroutine terminates.

Use case: Resource cleanup, connection closure, logging on coroutine exit.

Sources: src/foundation/src/helpers.php809-814

---

Implementation Patterns

Container Resolution Pattern

Most helper functions follow a consistent pattern for resolving services:

Sources: src/foundation/src/helpers.php347-380

Dual-Mode Helper Pattern

Many helpers support both retrieval and operation modes:

Mode	Example	Behavior
Retrieval	config()	Returns service instance
Get	config('app.name')	Returns specific value
Set	config(['app.name' => 'MyApp'])	Sets value(s)

Sources: src/foundation/src/helpers.php274-305

Fallback Pattern for Paths

Path helpers implement a fallback strategy for environments without container availability:

1. Check if ApplicationContext::hasContainer() returns true
2. If yes: Use container to get Application instance and call path method
3. If no: Check if BASE_PATH constant is defined
4. Use join_paths() to combine BASE_PATH with path segment
5. Throw RuntimeException if BASE_PATH is not defined

Sources: src/foundation/src/helpers.php99-229

---

Helper Function Registration

Global helper functions are defined in the foundation package's helpers file, which is loaded during application bootstrap. Each function is wrapped in an existence check to allow applications to override default implementations:

This pattern enables:

• User overrides of framework helpers
• Compatibility with other packages defining similar functions
• Conditional helper availability based on installed packages

Sources: src/foundation/src/helpers.php41-815