Features

Represents a human-readable app feature in a class, named the way you would describe it to your colleagues and clients. It contains the logic of implementing the feature with minimum friction and level of detail to remain concise and straight to the point.

It runs Lucid Units: Jobs and Operations to perform its tasks. They are thought of as the steps in the process of serving its purpose. A Feature can be served from anywhere, most commonly Controllers and Commands. Can also be queued to run asynchronously using Laravel’s powerful Queueing capabilities.

Technically, it is a class that encapsulates all the functionalities required for a single request/response lifecycle (or command), in which the handle method represents the task list when you want to implement it in your application.

Example: This is how a Feature class typically looks like. (simplified)

class UpdateProductFeature extends Feature
{
    public function __construct(private string $id) {}

    public function handle(Request $request)
    {
        $this->run(new ValidateProductInputJob($request->input()));

        $product = $this->run(new SaveProductJob(
            id: $this->id,
            title: $request->input('title'),
            price: $request->input('price'),
        ));

        return $this->run(new RespondWithJsonJob($product));
    }
}

Responsibility: Perform the steps required to accomplish the feature by running Jobs and Operations.

class UserController extends Controller
{
    public function login()
    {
        return $this->serve(new LoginUserFeature());
    }
}

Generate Feature Class

Use lucid CLI to generate a Feature class that extends Lucid’s Feature base class by default, which allows us to run jobs and operations using the built-in run method.

 lucid make:feature ListProducts

 lucid make:feature ListProducts Commerce

The generated Feature class will automatically be suffixed with Feature, so the class above will be ListProductsFeature.

Features can also be generated in subdirectories by specifying their paths

 lucid make:feature Thread/AddThread Forum

Generated class will be at app/Services/Forum/Features/Thread/AddThreadFeature.php

Inside Features

There are two essential highlights in a feature:

1. Signature (a.k.a constructor parameters): Looking at the signature of the Feature should give the idea of what is required for it to be served.
2. handle method: Looking at the class’s handle method should provide an overview of the steps required to serve the feature to the user (or any consuming party) without having to know too much details about the inner workings of each step. More on this at below.

class CreateArticleFeature extends Feature
{
    public function handle(Request $request)
    {
        $this->run(new ValidateArticleInputJob($request->input()));

        $this->run(new UploadFilesToCDNJob($request->input('files')));

        $slug = $this->run(new GenerateSlugJob($request->input('title')));

        $article = $this->run(new SaveArticleJob(
                title: $request->input('title'),
                body: $request->input('body'),
                slug: $slug,
        ));

        return $this->run(new RespondWithJsonJob($article));
    }
}

As shown in the example above, there are several ways to run Jobs in features that are explained in details in the definition of Jobs.

The handle method

Lucid units (Feature, Job, Operation) are simply classes extending Laravel’s base Job class with extra functionality that ties them together. Hence, the use of handle method as the invocation point for each of these units.

public function handle(Request $request)

This method is called automatically when running $this->serve(Feature::class) or $this->serve(new Feature()) and it goes through Laravel’s IoC to resolve dependencies. In this example we included the Request class to be resolved so that we can access it and pass input to Jobs. Request could’ve been any other class in the application that can be resolved using IoC.

public function handle(MyCustomClass $mcc)

This is the recommended way of using classes to maintain testability by interchanging class instances with their mocks.

Serving Features

You may serve features from anywhere in your application! Here are some exapmles of doing so.

HTTP

If your controller is generated through the lucid command, all you need to do is call serve within the controller method, otherwise, have your controller (or parent controller) extend Lucid’s controller Lucid\Units\Controller.

use Lucid\Units\Controller;
use App\Features\UpdateProductsFeature;

class ProductController extends Controller
{
    public function products()
    {
        return $this->serve(new ListProductsFeature());
    }
}

Command

To run a feature from the command we just need to equip our Command class with Lucid’s methods by simply using ServesFeatures

use Illuminate\Console\Command;
use App\Features\CleanStaleCartsFeature;
use Lucid\Bus\ServesFeatures;

class CleanStaleCarts extends Command
{
    use ServesFeatures;

    protected $signature = 'clean:carts --stale';

    protected $description = "Cleans inactive customer carts.";

    public function handle()
    {
        return $this->serve(new CleanStaleCartsFeature());
    }
}

Other

Just like we did for Commands we may do the same in any class we want, by simply using ServesFeatures the serve method will be available.

use App\Features\DoSomethingFeature;
use Lucid\Bus\ServesFeatures;

class ToServeFeaturesHere
{
    use ServesFeatures;

    public function give()
    {
        return $this->serve(new GiveHighFiveFeature());
    }
}

Testing

When generating a feature with lucid make:feature a test class is automatically generated along, having markIncomplete() statement in a stub method as a reminder to fill the missing test.

Feature tests are equivalent to functional tests in a typical application. It is about testing how the feature would behave with a certain input combination from a user’s perspective.

If the feature is served over an HTTP request, the test would be about actually requesting the URL and passing parameters to receive the expected output, in addition to further assertions in the case of storage or other application aspects that require further assertion.

class UpdateProductDetailsFeatureTest extends TestCase
{
    public function test_successful_product_details_update()
    {
        $product = [
            'id' => $fake->uuid,
            'title' => $fake->sentence,
            'description' => $fake->text,
            'price' => $faker->randomNumber(2),
        ];

        // request
        $response = $this->put("/products/{$product['id']}", $product);
        $response->assertStatus(200)
                 ->assertJson([
                    'updated' => true
                 ]);

        // storage
        $stored = Product::find($production['id']);
        $this->assertEquals($product, $stored->toArray());
    }

    public function test_failing_product_details_update()
    {
        $product = [
            'id' => $fake->uuid,
            'title' => '', // cannot be empty
            'description' => $fake->text,
            'price' => $faker->randomNumber(2),
        ];

        $response = $this->put("/products/{$product['id']}", $product);
        $response->assertStatus(200)
                 ->assertJson([
                    'updated' => false,
                    'error' => [
                        'messages' => ['title field is required.'],
                    ],
                 ]);

        // storage - ensure original title is still in place
        $stored = Product::find($production['id']);
        $this->assertEquals('previous title', $stored->title);
    }
}

As far as functional testing goes, it is best to portray the usage of the feature from a broad perspective rather than digging into every detail of the steps of the function. Feature testing is usually considered to be the integration test between the units that make up the feature.

Mocking

It is recommended with feature tests to only mock what’s external to your application to preserve the quality guarantee . Mocks are usually for 3rd-party APIs and other services that we integrate with, but not for internals such as storage.

For this example we will assume that this feature runs from a command line rather than over HTTP.

app/Features/UpdateFacebookPostsFeature.php

class UpdateFacebookPostsFeature extends Feature
{
    public function handle()
    {
        $posts = $this->run(new FetchFacebookPostsJob());

        $this->run(new StoreFacebookPostsJob(
            posts: $posts,
        ));
    }
}

app/Domains/Facebook/Jobs/FetchFacebookPostsJob.php

class FetchFacebookPostsJob extends Job
{
    public function handle(FacebookClient $fb)
    {
        return $fb->posts();
    }
}

tests/Feature/UpdateFacebookPostsFeatureTest.php

class UpdateFacebookPostsFeatureTest extends TestCase
{
    public function test_successfully_fetching_facebook_posts()
    {
        $mFB = Mockery::mock(FacebookClient::class);
        $mFB->shouldReceive('get')->with($args)->andReturn($payload);

        $this->app->instance(FacebookClient::class, $mFB);

        $f = new UpdateFacebookPosts();
        $result = $f->handle();

        // 0 in CLI means success!
        $this->assertEquals(0, $result);
    }
}

As shown in FetchFacebookPostsJob the client has been injected, so we had to replace the instance in IoC to load our mocked instance instead of the real one.

FAQ

class UpdateProductDetailsFeature
{
    private $isApi;

    public function __construct(bool $isApi)
    {
        $this->isApi = $isApi;
    }

    public function handle(Request $request)
    {
        $this->run(new ValidateProductDeatilsInputJob(
            input: $request->input()
        ));

        $product = $this->run(new UpdateProductDetailsJob(
            title: $request->input('title'),
            description: $request->input('description'),
            price: $request->input('price'),
        ));

        if ($this->isApi) {
            return $this->run(new RespondWithJsonJob($product));
        }

        return $this->run(new RespondWithViewJob(
            view: 'product',
            data: compact('product'),
        ));
    }
}

public function handle(Request $request)
{
    $this->run(new ValidateProductDeatilsInputJob(
        input: $request->input()
    ));

    if ($this->isApi) {
        $user = $this->run(new GetUserByApiTokenJob(
            token: $request->input('token'),
        ));
    } else {
        $user = $this->run(new GetUserFromSessionJob());
    }

    $product = $this->run(new UpdateProductDetailsJob(
        title: $request->input('title'),
        description: $request->input('description'),
        price: $request->input('price'),
        user: $user,
    ));

    if ($this->isApi) {
        return $this->run(new RespondWithJsonJob($product));
    }

    return $this->run(new RespondWithViewJob(
        view: 'product',
        data: compact('product'),
    ));
}

class UpdateProductDetailsFeature
{
    public function handle(Request $request)
    {
        $this->run(new ValidateProductDeatilsInputJob(
            input: $request->input()
        ));

        $user = $this->run(new GetUserByApiTokenJob(
            token: $request->input('token'),
        ));

        $product = $this->run(new UpdateProductDetailsJob(
            title: $request->input('title'),
            description: $request->input('description'),
            price: $request->input('price'),
            user: $user,
        ));

        return $this->run(new RespondWithViewJob(
            data: compact('product'),
            view: 'web.product.update',
        ));
    }
}

class UpdateProductDetailsFeature
{
    public function handle(Request $request)
    {
        $this->run(new ValidateProductDeatilsInputJob(
            input: $request->input()
        ));
        
        $user = $this->run(new GetUserFromSessionJob());

        $product = $this->run(new UpdateProductDetailsJob(
            title: $request->input('title'),
            description: $request->input('description'),
            price: $request->input('price'),
            user: $user,
        ));

        return $this->run(new RespondWithViewJob(
            view: 'product',
            data: compact('product'),
        ));
    }
}