HypervelHypervel
Hypervel
Documentation
GitHub
Hypervel
Documentation
GitHub
  • Documentation

    • Prologue

      • Contributing Guide
    • Getting Started

      • Introduction
      • Installation
      • Configuration
      • Directory Structure
      • Deployment
    • Architecture Concepts

      • Request Lifecycle
      • Service Container
      • Service Providers
      • Facades
    • The Basics

      • Routing
      • Middleware
      • CSRF Protection
      • Controllers
      • Requests
      • Responses
      • Views
      • Blade Templates
      • URL Generation
      • Session
      • Validation
      • Error Handling
      • Logging
    • Digging Deeper

      • Artisan Console
      • Broadcasting
      • Cache
      • Collections
      • Context
      • Coroutine
      • Contracts
      • Events
      • File Storage
      • Helpers
      • HTTP Client
      • Localization
      • Mail
      • Notifications
      • Package Development
      • Package Porting
      • Processes
      • Queues
      • Rate Limiting
      • Strings
      • Task Scheduling
    • Security

      • Authentication
      • Authorization
      • Encryption
      • Hashing
    • Database

      • Getting Started
      • Query Builder
      • Pagination
      • Migrations
      • Seeding
      • Redis
    • Eloquent ORM

      • Getting Started
      • Relationships
      • Collections
      • Mutators / Casts
      • API Resources
      • Serialization
      • Factories
    • Testing

      • Getting Started
      • HTTP Tests
      • Console Tests
      • Database
      • Mocking
      • Packages Toolkit

Contracts

  • Introduction
    • Contracts vs. Facades
  • When to Use Contracts
  • How to Use Contracts
  • Contract Reference

Introduction

Hypervel's "contracts" are a set of interfaces that define the core services provided by the framework. For example, an Hypervel\Auth\Contracts\Gate contract defines the methods needed for authorizing a resource, while the Hypervel\Hashing\Contracts\Hasher contract defines the methods needed for generating a secure hash.

All of the contracts live separately in the Contracts directory in their belonging packages. This provides a quick reference point for all available contracts, as well as a single, decoupled package that may be utilized when building packages that interact with Hypervel services.

Contracts vs. Facades

Hypervel's facades and helper functions provide a simple way of utilizing Hypervel's services without needing to type-hint and resolve contracts out of the service container. In most cases, each facade has an equivalent contract.

Unlike facades, which do not require you to require them in your class' constructor, contracts allow you to define explicit dependencies for your classes. Some developers prefer to explicitly define their dependencies in this way and therefore prefer to use contracts, while other developers enjoy the convenience of facades. In general, most applications can use facades without issue during development.

When to Use Contracts

The decision to use contracts or facades will come down to personal taste and the tastes of your development team. Both contracts and facades can be used to create robust, well-tested Hypervel applications. Contracts and facades are not mutually exclusive. Some parts of your applications may use facades while others depend on contracts. As long as you are keeping your class' responsibilities focused, you will notice very few practical differences between using contracts and facades.

In general, most applications can use facades without issue during development. If you are building a package that integrates with multiple PHP frameworks you may wish to use the corresponding contracts to define your integration with Hypervel's services without the need to require Hypervel's concrete implementations in your package's composer.json file.

How to Use Contracts

So, how do you get an implementation of a contract? It's actually quite simple.

Many types of classes in Hypervel are resolved through the service container, including controllers, event listeners, middleware and even route closures. So, to get an implementation of a contract, you can just "type-hint" the interface in the constructor of the class being resolved.

For example, take a look at this event listener:

<?php

namespace App\Listeners;

use App\Events\OrderWasPlaced;
use App\Models\User;
use Hypervel\Cache\Contracts\Factory;

class CacheOrderInformation
{
    /**
     * Create a new event handler instance.
     */
    public function __construct(
        protected Factory $cache,
    ) {}

    /**
     * Handle the event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

When the event listener is resolved, the service container will read the type-hints on the constructor of the class, and inject the appropriate value. To learn more about registering things in the service container, check out its documentation.

Contract Reference

This table provides a quick reference to all of the Hypervel contracts and their equivalent facades:

ContractReferences Facade
Hypervel\Auth\Contracts\Authorizable 
Hypervel\Auth\Contracts\GateGate
Hypervel\Auth\Contracts\Authenticatable 
Hypervel\Auth\Contracts\FactoryContractAuth
Hypervel\Auth\Contracts\GuardAuth::guard()
Hypervel\Auth\Contracts\StatefulGuard 
Hypervel\Auth\Contracts\SupportsBasicAuth 
Hypervel\Auth\Contracts\UserProvider 
Hypervel\Bus\Contracts\DispatcherBus
Hypervel\Bus\Contracts\QueuingDispatcherBus::dispatchToQueue()
Hypervel\Broadcasting\Contracts\FactoryBroadcast
Hypervel\Broadcasting\Contracts\BroadcasterBroadcast::connection()
Hypervel\Broadcasting\Contracts\ShouldBroadcast 
Hypervel\Broadcasting\Contracts\ShouldBroadcastNow 
Hypervel\Cache\Contracts\FactoryCache
Hypervel\Cache\Contracts\Lock 
Hypervel\Cache\Contracts\LockProvider 
Hypervel\Cache\Contracts\RepositoryCache::driver()
Hypervel\Cache\Contracts\Store 
Hypervel\Config\Contracts\RepositoryConfig
Hypervel\Container\Contracts\ContainerApp
Hypervel\Foundation\Exceptions\Contracts\ExceptionHandler 
Hypervel\Encryption\Contracts\EncrypterCrypt
Hypervel\Event\Contracts\DispatcherEvent
Hypervel\Filesystem\Contracts\CloudStorage::cloud()
Hypervel\Filesystem\Contracts\FactoryStorage
Hypervel\Filesystem\Contracts\FilesystemStorage::disk()
Hypervel\Foundation\Contracts\ApplicationApp
Hypervel\Console\Contracts\Application 
Hypervel\Foundation\Console\Contracts\KernelArtisan
Hypervel\Hashing\Contracts\HasherHash
Hypervel\Mail\Contracts\MailQueueMail::queue()
Hypervel\Mail\Contracts\Mailable 
Hypervel\Mail\Contracts\MailerMail
Hypervel\Notifications\Contracts\DispatcherNotification
Hypervel\Notifications\Contracts\FactoryNotification
Hypervel\ObjectPool\Contracts\Factory 
Hypervel\ObjectPool\Contracts\ObjectPool 
Hypervel\ObjectPool\Contracts\Recycler 
Hypervel\Queue\Contracts\EntityResolver 
Hypervel\Queue\Contracts\FactoryQueue
Hypervel\Queue\Contracts\Job 
Hypervel\Queue\Contracts\MonitorQueue
Hypervel\Queue\Contracts\QueueQueue::connection()
Hypervel\Queue\Contracts\QueueableCollection 
Hypervel\Queue\Contracts\QueueableEntity 
Hypervel\Queue\Contracts\ShouldQueue 
Hypervel\Foundation\Exceptions\Contracts\ExceptionHandler 
Hypervel\Foundation\Exceptions\Contracts\ExceptionRenderer 
Hypervel\Foundation\Http\Contracts\ExceptionRenderer 
Hypervel\Cookie\Contracts\CookieCookie
Hypervel\Http\Contracts\RequestContractRequest
Hypervel\Http\Contracts\ResponseContractResponse
Hypervel\Router\Contracts\UrlGeneratorURL

Info

The contracts in Hyperf can refer to hyperf/contract package

Edit this page
Last Updated:
Contributors: Albert Chen
Prev
Coroutine
Next
Events