Forem: Alexandr

Getters and Setters in Objects

Alexandr — Wed, 26 Mar 2025 20:45:50 +0000

In programming, there are many different approaches to structuring code. For example, the procedural style—familiar from school or university—where a program is described as a series of sequential instructions:

step1($data);
step2($data);
step3($data);

This programming style is easy to grasp and was the main approach for many years in languages such as C, Pascal, and others.

However, in modern PHP and frameworks like Laravel, the object-oriented approach is commonly used. In this paradigm, we create classes, instantiate them, and use methods to manage the behavior of objects. OOP is based on the idea that data and behavior should be encapsulated within a single “living” object. For example, consider the App class:

$app = new App();

$app->start();

In this case, we don't instruct the program step by step; instead, we delegate the complete initialization and execution to the object. This approach hides implementation details and provides a clean interface for interacting with the object.

Yet, there is a vast amount of code and practices in OOP languages that remain procedural in nature. Let’s explore a few examples.

Dumb Objects Lead to Procedural Code

There is a common practice where an object is used purely as a container for data—it contains no business logic, only data storage. Consider the following example:

class User
{
    private string $name;
    private string $email;

    public function getName(): string
    {
        return $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }

    public function getEmail(): string
    {
        return $this->email;
    }

    public function setEmail(string $email): void
    {
        $this->email = $email;
    }
}

Such a class is often mistakenly called a "Data Transfer Object" (DTO), but that's not accurate. A DTO should be immutable, and having setters violates that principle.

Here, the User object is used solely for storing data. Later, this data is processed in various parts of the application. For instance:

// In one part of the code, an object is created and populated with data
$user = new User();
$user->setName('John Doe');
$user->setEmail('john.doe@example.com');

// In another part of the code, the data is validated
$validator = new Validator();
$validator->validate($user);

// In yet another part of the code, an email is sent to the user
$notification = new WelcomeNotification();
$notification->send($user->getEmail());

In this example, the User object doesn't possess its own logic—external classes like Validator and Mailer handle data processing. Essentially, rather than using an array to store information, we use an object; however, the business logic is moved outside it. This results in an architecture that is closer to procedural programming, where the program consists of a set of functions acting upon data.

A similar situation is observed in ORMs that do not use the Active Record pattern, such as Doctrine:

$entityManager = EntityManager::create($connection, $config);

// Create a user object
$user = new User();
$user->setName("John Doe");
$user->setEmail("john.doe@example.com");

// Save to the database
$entityManager->persist($user);
$entityManager->flush();

This contradicts the principles of object-oriented programming because objects should be responsible for their own data and behavior.

As a result, we end up with a system where logic is distributed between “dumb” objects and procedural sections of code. This separation of responsibilities makes the application harder to understand, test, and further develop.

Tell, Don’t Ask

Tell, Don’t Ask is a well-articulated principle of quality object-oriented design that helps in creating a clean and maintainable architecture.

"Don't ask an object for data to make a decision—tell the object what to do."

At first glance, this principle might seem to contradict the Single Responsibility Principle (SRP), but in real-world development, you often have to choose which principle is more important in a given context. Still, the more principles you manage to adhere to simultaneously, the better.

Instead of creating a “dumb” object, you can encapsulate business logic directly within the object or in a related service. For example, if you need to validate data and send a welcome email, you can delegate this responsibility to an object or service that knows how to handle it. Consider the following two approaches:

Rather than extracting data and validating it externally, let the object perform the necessary action itself:

class User
{
    protected string $name;
    protected string $email;

    private function validate(): bool
    {
        $validator = Validator::make([
            'name'  => $this->name,
            'email' => $this->email,
        ], [
            'name'  => 'required',
            'email' => 'required|email',
        ]);

        return $validator->passes();
    }

    public function register(): void
    {
        $this->validate();

        // Save the user to the database...

        $this->notify(WelcomeNotification::class);
    }
}

$user = new User(
    name: "John Doe",
    email: "john.doe@example.com"
);

$user->register();

Here, the object itself performs validation and sends notifications rather than simply exposing data for external manipulation.

Additionally, the Tell, Don’t Ask principle works well with the Law of Demeter (LoD), which also promotes the creation of more resilient and independent objects.

For further reading, you can explore works by Martin Fowler, Allen Holub, and Yegor Bugayenko.

When Files Ask for a Password: A Developer's Solution

Alexandr — Wed, 12 Mar 2025 18:58:24 +0000

In my online world, everything was simple—a login and password were all it took: familiar, secure, and convenient.

The Challenge

Then I stumbled upon a parallel reality: password-protected files like PDF, DOC, ZIP, and more. This wasn’t a rare glitch but a widespread practice in some industries, reminiscent of the floppy disk era. My program, built for modern interactions, would freeze at the sight of such files, bluntly declaring:

"Sorry, we don’t work with these things."

I wasn’t willing to accept this limitation or force users to change long-standing habits. The solution was clear: empower the system to handle these files.

The Journey

PDFs:

I began with PDFs—the cornerstone of document workflows. After testing several PHP libraries from GitHub, which worked until confronted with “quirky” PDFs (errant line breaks or documents that cheekily included /encrypt twice), I discovered qpdf. This external tool reliably handled even the most exotic PDFs.

Office Files:

With .DOCX files, the process was relatively smooth. But the venerable .DOC? Some companies cling to it like a cherished relic, and PHP libraries for this format are scarce. Eventually, msoffcrypto-tool proved to be a true lifesaver.

Archives:

Since I was already integrating external programs via Symfony/Process, I turned to the time-tested 7-Zip for handling archives.

Introducing Lumos

Thus was born Lumos—a cohesive library combining all these tools to effortlessly handle password-protected files. The project is available on GitHub. I’m not expecting accolades or pull requests; I just hope it makes another developer’s life a little easier.

Have you ever encountered password-protected files?

Usage Laravel and ChatGPT "Function calling"

Alexandr — Mon, 19 Jun 2023 00:28:41 +0000

Recently, OpenAI released an update for ChatGPT, introducing new features that allow developers to describe language model functions - gpt-4-0613 and gpt-3.5-turbo-0613. These features enable the generation of JSON objects containing arguments to run these functions based on user input.

Let's explore an example of this new feature. You can use it to obtain information about an IP address, previous orders, information from your FAQ, weather forecast, or any other desired information.

To demonstrate how it works, we will use the openai-php/client library. Firstly, create an Artisan command by running the following command:

php artisan make:command ChatFunction

Update the ChatFunction class as follows:

namespace App\Console\Commands;

use Illuminate\Console\Command;
use OpenAI\Client;

class ChatFunction extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'app:chat-function';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Invoke a chat function with OpenAI language model.';

    /**
     * Execute the console command.
     *
     * @return mixed
     */
    public function handle()
    {
        $client = new Client(config('openai.api_key'));

        $response = $client->chat()->create([
            'model'    => 'gpt-3.5-turbo-0613',
            'messages' => [
                ['role' => 'user', 'content' => 'What do you know about IP address 12.175.87.227?'],
            ],
        ]);

        $answer = $response->choices[0]->message->content;

        $this->info("OpenAI response: $answer");
    }
}

If we ask AI for information about a specific IP address, it may respond with something like, "I'm sorry, but I cannot provide information about specific IP addresses."

To fix this, let's specify the function in our request.

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ChatFunction extends Command
{
    public function handle()
    {
        $client = \OpenAI::factory()
            ->withApiKey(config('openai.api_key'))
            ->make();

        $response = $client->chat()->create([
            'model'     => 'gpt-3.5-turbo-0613',
            'messages'  => [
                ['role' => 'user', 'content' => 'What do you know about IP 12.175.87.227 ?'],
            ],
            'functions' => [
                [
                    'name'        => 'about_ip',
                    'description' => 'Get information about the IP address',
                    'parameters'  => [
                        'type'       => 'object',
                        'properties' => [
                            'ip' => [
                                'type'        => 'string',
                                'description' => 'IP address v4',
                            ],
                        ],
                        'required'   => ['ip'],
                    ],
                ],
            ],
        ]);

        // As we can see, we now have a proposal to call a function on our side and there are arguments:  
        $name = $response->choices[0]->message->functionCall->name; // ip_info  
        $arguments = $response->choices[0]->message->functionCall->arguments; // {\n "ip": "12.175.87.227" }  
    }
}

Now we have prepared data such as the name of the function to be called and its arguments. I believe that an excellent solution for performing such tasks is to use the Sajya package, which simplifies working with JSON-RPC both in the console and as an API. Therefore, let's create a simple class using this package:

Command to create a new procedure called "AboutIp" using Laravel's artisan CLI:

php artisan make:procedure AboutIp

Now, let's add a useful action to it:

namespace App\Http\Procedures;  

use Illuminate\Support\Collection;  
use Illuminate\Support\Facades\Http;  
use Sajya\Server\Procedure;  

class AboutIp extends Procedure  
{  
    /**  
     * The name of the procedure that is used for referencing.  
     * 
     * @var string  
     */  
    public static string $name = 'about';  

    /**  
     * Execute the procedure.  
     * 
     * @param string $ip  
     * @return Collection  
     */  
    public function ip(string $ip): Collection  
    {  
        return Http::get('http://ip-api.com/json/' . $ip)->collect();  
    }  
}

This "about_ip" procedure will simply receive an IP address, fetch information from another API, and return it to the user.

Let's go back to the console command and add a method to create and call the Remote Procedure Call (RPC):

protected function callRPC(string $method, ?string $params = null): ?string
{
    $app = new App([
        \App\Http\Procedures\AboutIp::class,
    ], '_');

    $response = $app->terminate(json_encode([
        'jsonrpc' => '2.0',
        'method'  => $method,
        'params'  => json_decode($params, true),
        'id'      => 1,
    ]));

    return json_encode($response, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
}

If we call it just by its name and arguments, we won't receive a human response. To obtain that, we need to refer back to ChatGPT:

/**
 * Execute the console command.
 */
public function handle()
{
    $client = \OpenAI::factory()
        ->withApiKey(config('openai.api_key'))
        ->make();

    $response = $client->chat()->create([
        'model'     => 'gpt-3.5-turbo-0613',
        'messages'  => [
            ['role' => 'user', 'content' => 'What do you know about IP 12.175.87.227 ?'],
        ],
        'functions' => [
            [
                'name'        => 'about_ip',
                'description' => 'Get information about the IP address',
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => [
                        'ip' => [
                            'type'        => 'string',
                            'description' => 'IP address v4',
                        ],
                    ],
                    'required'   => ['ip'],
                ],
            ],
        ],
    ]);

    // As we can see, we now have a proposal to call a function on our side and there are arguments:
    $name = $response->choices[0]->message->functionCall->name; // ip_info
    $arguments = $response->choices[0]->message->functionCall->arguments; // {\n "ip": "12.175.87.227" }


    $functionResult = $this->callRPC($name, $arguments);

    // Again we turn to ChatGPT, but this time we add the response from the function:
    $response = $client->chat()->create([
        'model'     => 'gpt-3.5-turbo-0613',
        'messages'  => [
            ['role' => 'user', 'content' => 'What do you know about IP 12.175.87.227 ?'],
            ['role' => 'function', 'name' => $name, 'content' => $functionResult],
        ],
        'functions' => [
            [
                'name'        => 'about_ip',
                'description' => 'Get information about the IP address',
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => [
                        'ip' => [
                            'type'        => 'string',
                            'description' => 'IP address v4',
                        ],
                    ],
                    'required'   => ['ip'],
                ],
            ],
        ],
    ]);

    $response->choices[0]->message->content;

    // The IP address 12.175.87.227 is located in San Diego, California, United States.
    // The postal code is 92110.
    // The latitude and longitude coordinates are 32.7616 and -117.2058 respectively.
    // The timezone of this location is America/Los_Angeles.
    // The ISP (Internet Service Provider) is AT&T Services, Inc.
    // The organization associated with this IP address is Coffman Specialties.
    // The Autonomous System (AS) number is AS7018 AT&T Services, Inc.
}

Now we got a human response and used the ChatGPT "features" to enrich the actual information.

Use inline SVG icons with Laravel

Alexandr — Mon, 14 Dec 2020 13:16:07 +0000

I used icons in fonts for a long time, just by connecting a file with styles and insert a tag with class names.

<i class="icon icon-home">

It was quite simple. But over time, the began to use SVG format instead of fonts. Now, for the same post, it was not required to include styles, but the tag itself became much larger:

<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-house" viewBox="0 0 16 16">
  <path fill-rule="evenodd" d="M2 13.5V7h1v6.5a.5.5 0 0 0 .5.5h9a.5.5 0 0 0 .5-.5V7h1v6.5a1.5 1.5 0 0 1-1.5 1.5h-9A1.5 1.5 0 0 1 2 13.5zm11-11V6l-2-2V2.5a.5.5 0 0 1 .5-.5h1a.5.5 0 0 1 .5.5z"/>
  <path fill-rule="evenodd" d="M7.293 1.5a1 1 0 0 1 1.414 0l6.647 6.646a.5.5 0 0 1-.708.708L8 2.207 1.354 8.854a.5.5 0 1 1-.708-.708L7.293 1.5z"/>
</svg>

If the past could be remembered or rely on the IDE's auto-hints, then the inline tag is more difficult. I started looking for options on how to keep this in mind without complicating it. So I decided to write my own simple package that could display any icons by file name.

namespace App\Providers;

use Orchid\Icons\IconFinder;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(IconFinder $iconFinder) : void
    {
        $iconFinder->registerIconDirectory('fa', storage_path('app/fontawesome'));
    }
}

When calling the directory method with the first argument, we pass the prefix to call our icons and the second directory where they are located.

After that, we can call the component in our blade templates:

<x-orchid-icon path="fa.home" />

If you use one or two sets of icons that do not repeat, then it is not necessary to specify a prefix in the component:

<x-orchid-icon path="home" />

You can also list some attributes that should be applied to your icon:

<x-orchid-icon 
    path="home" 
    class="icon-big" 
    width="2em" 
    height="2em" />

As you can see, this is as simple as the past use of the tag with class names. And it is not tied to any set of icons. We independently from our set.

You can find this package on GitHub, in the place with the description: https://github.com/orchidsoftware/blade-icons

Laravel Orchid - SVG Icons

Alexandr — Sat, 19 Sep 2020 12:15:47 +0000

In the latest release of the package, I worked on replacing Icon Fonts in favor of the SVG format, which means that now icons are available in a vector.

Previously, if you needed to display your own (or from the Internet) icon, then you had to translate it into a font and include a CSS file with a description, now this is not needed. It is enough to copy the desired icon to the project.

Let's do it together. Let's say we want to include an icon from the popular Font Awesome. To do this, select a suitable storage directory, for example, create a new icons directory and a fontawesome subdirectory:

resources
  - css 
  - icons
      -- fontawesome 
  - js
  - lang
  - views

Load the appropriate icons into the new directory, for example, this notebook icon. Then we will indicate to the package the directory in which we need to search for our images, for this we will edit the configuration file config/platform.php:

'icons' => [
    'fa' => resource_path('icons/fontawesome')
],

All we have done here is declare the prefix by which we will refer to fa and the directory where the files are located.
To display in the components of the package, you only need to pass the prefix + name, for example, the definition of the icon in the menu will look like this:

ItemMenu::label('Example of custom icons')
    ->icon('fa.address-book')
    ->url(#);

Moreover, if for some reason your project does not have Laravel Orchid, then a separate package has been prepared for the Blade and SVG template engine.

Draw model charts in Laravel Orchid

Alexandr — Tue, 04 Aug 2020 21:53:25 +0000

Building charts can be awkward, but since 7.15.0, a trait has been added to Laravel Orchid to generate group and time data.

To use it, you should add the trait Orchid\Metrics\Chartable to the model.

Let's try it in action and form a visual dynamics of user registrations. To do this, let's create a new layer using the command:

 php artisan orchid:chart DynamicsOfRegistrations

In app/Orchid/Layouts directory a new class will be created, we will add the name and the target key to it:

namespace App\Orchid\Layouts;

use Orchid\Screen\Layouts\Chart;

class DynamicsOfRegistrations extends Chart
{
    /**
     * Add a title to the Chart.
     *
     * @var string
     */
    protected $title = 'New members';

    /**
     * Data source.
     *
     * The name of the key to fetch it from the query.
     * The results of which will be elements of the chart.
     *
     * @var string
     */
    protected $target = 'registrations';
}

The standard package comes with a screen displaying all users, why not use it. Let's add a new query value to the UserListScreen:

public function query(): array
{
    return [
        'registrations' => [
            User::countByDays()->toChart('Users'),
        ],
        // ... other values
    ]
}

All that's left is to put a layer on the screen:

public function layout(): array
{
    return [
        DynamicsOfRegistrations::class,
        // ... other layouts
    ];
}

Now going to the user list page, we will see how many users have registered in the last month:

That's great, isn't it? But let's also show the statistics of how many users have enabled two-factor authentication (by the way, here is an article on how to enable it). For this, we will also create a new layer, but with different values:

namespace App\Orchid\Layouts;

use Orchid\Screen\Layouts\Chart;

class UsageTwoFactorAuth extends Chart
{
    /**
     * Add a title to the Chart.
     *
     * @var string
     */
    protected $title = 'Usage two-factor authentication';

    /**
     * Available options:
     * 'bar', 'line',
     * 'pie', 'percentage'.
     *
     * @var string
     */
    protected $type = 'pie';

    /**
     * Data source.
     *
     * The name of the key to fetch it from the query.
     * The results of which will be elements of the chart.
     *
     * @var string
     */
    protected $target = 'usageTwoFactorAuth';
}

The output of the request will be slightly different:

public function query(): array
{
    $usageTwoFactorAuth = User::countForGroup('uses_two_factor_auth')
        ->toChart(function (bool $state) {
            return $state ? 'Enabled' : 'Disabled';
        });


    return [
        'usageTwoFactorAuth' => $usageTwoFactorAuth,
        // ...
    ]
}

Let's not forget to bring out the layer created:

public function layout(): array
{
    return [
        DynamicsOfRegistrations::class,
        UsageTwoFactorAuth::class
        // ... other layouts
    ];
}

Now, going to the user list page, we will also see the ratio of users who have enabled two-factor authentication:

That's it! Our minimum example is ready, you can learn more about building charts on the documentation page.

How to enable two-factor authentication in Laravel Orchid

Alexandr — Tue, 04 Aug 2020 09:43:21 +0000

Two-factor authentication

Two-factor authentication provides your users with additional account security, requiring them to provide a token at login time in addition to their username and password.

Laravel Orchid - what is it?

This is a package for building administration-style applications using the Laravel framework. It is most often used to build back-office applications, admin panels, and content management systems. You can see the differences from Nova, Voyager, BackPack, QuickAdminPanel on the description page

Configuring

By default, the TOTP algorithm is used as the two-factor authentication provider. To enable it, you need to call a static method in the service provider:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Orchid\Support\Facades\Dashboard;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Dashboard::useTwoFactorAuth();
    }
}

Now the login form adds a token validation for the accounts upon authorization.

Now let's go to the profile page:

In the settings, select the "Two Factor Authentication" item, a modal window opens:

At this stage, we need an application that supports TOTP, for example, Google Authenticator (Available on iOS and Android)

Scan the offered QR code or manually enter the TOTP code.
The app now generates short temporary codes:

To enable, it remains only to enter the code from the phone into the modal window.

Now, when entering the panel, a temporary code will be requested:

That's all. This way we made our application safer. Even if someone receives a login and password for an account, they will also need physical access to your phone to enter the time code.

Reusing layers in Laravel Orchid

Alexandr — Tue, 28 Jul 2020 10:02:02 +0000

Layouts are easy to reuse when fields are related to the relations of different models.

Already during installation, we have a layer for defining permissions, which is used immediately at the user and roles editing screen.

But sometimes you want to apply the same set of fields with different values. Let's consider an example when you need to specify an address.

Such a set will be both for the client, the customer, and it will appear twice on the same form (for example, in order, delivery and invoice). To solve this situation, you do not need to create and describe almost identical layouts. Instead, let's add logic to one single layer.

namespace App\Orchid\Layouts;

use Orchid\Screen\Field;
use Orchid\Screen\Fields\Input;
use Orchid\Screen\Fields\Label;
use Orchid\Screen\Layouts\Rows;

class AddressLayout extends Rows
{
    /**
     * Used to create the title of a group of form elements.
     *
     * @var string|null
     */
    protected $title;

    /**
     * Prefix for a field name
     *
     * @var string
     */
    protected $prefix;

    /**
     * ReusableEditLayout constructor.
     *
     * @param string      $prefix
     * @param string|null $title
     */
    public function __construct(string $prefix, string $title = null)
    {
        $this->prefix = $prefix;
        $this->title = $title;
    }

    /**
     * Views.
     *
     * @return Field[]
     */
    protected function fields(): array
    {
        return [
            Input::make($this->prefix . '.address')
                ->required()
                ->title('Address')
                ->placeholder('177A Bleecker Street'),
        ];
    }
}

Now, when used, we will pass the prefix and header values:

public function layout(): array
{
    return [
        Layout::columns([
            new AddressLayout('order.shipping_address', 'Shipping Address'),
            new AddressLayout('order.invoice_address', 'Invoice Address'),
        ]),
    ];
}

But this is also inconvenient. Why? Now in the definition, we will think, do we need to end the prefix with a dot? And also specify strange names through the concatenation $this->prefix. '.address'.

Let's fix it! Since the main thing is to return an array of objects, you can modify the fields before returning, as well as take care of the point in the constructor:

namespace App\Orchid\Layouts;

use Illuminate\Support\Str;
use Orchid\Screen\Field;
use Orchid\Screen\Fields\Input;
use Orchid\Screen\Layouts\Rows;

class AddressLayout extends Rows
{
    /**
     * Used to create the title of a group of form elements.
     *
     * @var string|null
     */
    protected $title;

    /**
     * Prefix for a field name
     *
     * @var string
     */
    protected $prefix;

    /**
     * ReusableEditLayout constructor.
     *
     * @param string      $prefix
     * @param string|null $title
     */
    public function __construct(string $prefix, string $title = null)
    {
        $this->prefix = Str::finish($prefix, '.');
        $this->title = $title;
    }

    /**
     * Get the fields elements to be displayed.
     *
     * @return Field[]
     */
    protected function fields(): array
    {
        return $this->addPrefix([
            Input::make('address')
                ->required()
                ->title('Address')
                ->placeholder('177A Bleecker Street'),
        ]);
    }

    /**
     * @param Field[] $fields
     *
     * @return array
     */
    protected function addPrefix(array $fields): array
    {
        return array_map(function (Field $field) {
            return $field->set('name',
                $this->prefix . $field->get('name')
            );
        }, $fields);
    }
}

The main task has been solved. Now, the reuse of a class with one set of fields for the address does not make you think and duplicate the same thing.

Admin for Laravel

Alexandr — Wed, 01 Jul 2020 20:03:46 +0000

For laravel, there are many different packages for building internal applications. Laravel Nova, Backback, and many others. But for his internal administration application, I chose a lesser-known package called Laravel Orchid.

This package provides the concept of "Screens", this is when you explicitly determine what should be on one page at once. This approach is very different from what you saw before.
No need to worry about crud operations, or the mandatory use of eloquent models.

You in one class determine which methods can be called from the page, which tables, line graphs, etc. will be displayed. You do not have to create a model and its resources. The screen does not know where the data comes from, it can be: a database, API, or any other external sources. Therefore, it is more effective than packages rigidly based on simple operations, beyond which you cannot use their user interfaces

Boring. Show me the code!

No problem, let's make an example of sending an email message to the user.

First, you need to create a screen to display the submission form, using the command:

php artisan orchid:screen EmailSenderScreen

A new file EmailSenderScreen.php will be created in the app/Orchid/Screens directory:

namespace App\Orchid\Screens;

use Orchid\Screen\Screen;

class EmailSenderScreen extends Screen
{
    /**
     * Name and description properties are responsible for
     * what name will be displayed
     * on the user screen and in headlines.
     */
    public $name = 'EmailSenderScreen';
    public $description = 'EmailSenderScreen';

    /**
     * A method that defines all screen input data
     * is in it that database queries should be called,
     * API or any others (not necessarily explicit),
     * the result of which should be an array,
     * appeal to which his keys will be used.
     */
    public function query(): array
    {
        return [];
    }

    /**
     * Identifies control buttons and events.
     * which will have to happen by pressing
     */
    public function commandBar(): array
    {
        return [];
    }

    /**
     * Set of mappings
     * rows, tables, graphs,
     * modal windows, and their combinations
     */
    public function layout(): array
    {
        return [];
    }
}

The main difference of the screen from the controller is the structure defined in advance, which serves
only one-page defining data and events.

Like the controller, the screen needs to be registered in the route file,
Define it in the file for the admin panel routes/platform.php:

use App\Orchid\Screens\EmailSenderScreen;

Route::screen('email', EmailSenderScreen::class)->name('platform.email');

After we have registered a new route, you can go to the browser at /dashboard/email,
to look at the empty screen, fill it with the elements.

Add a name and description:

/**
 * Display header name.
 *
 * @var string
 */
public $name = 'Email sender';

/**
 * Display header description.
 *
 * @var string
 */
public $description = 'Tool that sends ad-hoc email messages.';

To display the input fields, we describe them in the Layouts method:

use Orchid\Screen\Fields\Input;
use Orchid\Screen\Fields\Quill;
use Orchid\Screen\Fields\Relation;
use Orchid\Screen\Layout;

/**
 * Views.
 *
 * @return Layout[]
 */
public function layout(): array
{
    return [
        Layout::rows([
            Input::make('subject')
                ->title('Subject')
                ->required()
                ->placeholder('Message subject line')
                ->help('Enter the subject line for your message'),

            Relation::make('users.')
                ->title('Recipients')
                ->multiple()
                ->required()
                ->placeholder('Email addresses')
                ->help('Enter the users that you would like to send this message to.')
                ->fromModel(User::class,'name','email'),

            Quill::make('content')
                ->title('Content')
                ->required()
                ->placeholder('Insert text here ...')
                ->help('Add the content for the message that you would like to send.')

        ])
    ];
}

Now our page has some elements but does not produce any action.
to define them you need to create a new public method and specify a link to it in commandBar:

namespace App\Orchid\Screens;

use App\User;
use Illuminate\Http\Request;
use Illuminate\Mail\Message;
use Illuminate\Support\Facades\Mail;
use Orchid\Screen\Fields\Input;
use Orchid\Screen\Fields\Quill;
use Orchid\Screen\Fields\Relation;
use Orchid\Screen\Layout;
use Orchid\Screen\Actions\Button;
use Orchid\Screen\Screen;
use Orchid\Support\Facades\Alert;

class EmailSenderScreen extends Screen
{
    /**
     * Display header name.
     *
     * @var string
     */
    public $name = 'Email sender';

    /**
     * Display header description.
     *
     * @var string
     */
    public $description = 'Tool that sends ad-hoc email messages.';

    /**
     * Query data.
     *
     * @return array
     */
    public function query(): array
    {
        return [];
    }

    /**
     * Button commands.
     *
     * @return Link[]
     */
    public function commandBar(): array
    {
        return [
            Button::make('Send Message')
                ->icon('icon-paper-plane')
                ->method('sendMessage')
        ];
    }

    /**
     * Views.
     *
     * @return Layout[]
     */
    public function layout(): array
    {
        return [
            Layout::rows([
                Input::make('subject')
                    ->title('Subject')
                    ->required()
                    ->placeholder('Message subject line')
                    ->help('Enter the subject line for your message'),

                Relation::make('users.')
                    ->title('Recipients')
                    ->multiple()
                    ->required()
                    ->placeholder('Email addresses')
                    ->help('Enter the users that you would like to send this message to.')
                    ->fromModel(User::class,'name','email'),

                Quill::make('content')
                    ->title('Content')
                    ->required()
                    ->placeholder('Insert text here ...')
                    ->help('Add the content for the message that you would like to send.')

            ])
        ];
    }

    /**
     * @param Request $request
     *
     * @return \Illuminate\Http\RedirectResponse
     */
    public function sendMessage(Request $request)
    {
        $request->validate([
            'subject' => 'required|min:6|max:50',
            'users'   => 'required',
            'content' => 'required|min:10'
        ]);

        Mail::raw($request->get('content'), function (Message $message) use ($request) {

            $message->subject($request->get('subject'));

            foreach ($request->get('users') as $email) {
                $message->to($email);
            }
        });


        Alert::info('Your email message has been sent successfully.');
        return back();
    }
}

After that, can to send email messages to addresses.

Note that by default the SMTP driver enabled for sending mail,
You can change it in the .env file to log for verification.

Since our utility mixed up, we can dream up and imagine that our boss asked us to put the title of our messages like “Campaign news for July”, but be able to change it. To do this, add the key to the query method with the name of our element:

/**
 * Query data.
 *
 * @return array
 */
public function query(): array
{
    return [
        'subject' => date('F').' Campaign News',
    ];
}

Now the field with the name subject automatically fits the value from the result.

This is a very simple example, but the development process will be identical in many aspects. I really like this approach, because you do not need to keep a lot of things in mind. Looking at one single class, it’s immediately clear what is happening on the page. If you are interested, then you can find more examples on the site orchids.software

RPC-like API for your Laravel project

Alexandr — Fri, 08 May 2020 19:30:13 +0000

JSON-RPC 2.0 this is a simple stateless protocol for creating an RPC (Remote Procedure Call) style API. It usually looks as follows:

You have one single endpoint on the server that accepts requests with a body of the form:

{"jsonrpc": "2.0", "method": "post.like", "params": {"post": "12345"}, "id": 1}

And it returns answers of the view:

{"jsonrpc": "2.0", "result": {"likes": 123}, "id": 1}

If an error occurs - the error response:

{"jsonrpc": "2.0", "error": {"code": 404, "message": "Post not found"}, "id": "1"}

And it's all! Did I say that is easy?

Bonus support batch operations:

Request:

[
   {"jsonrpc":"2.0","method":"server.shutdown","params":{"server":"42"},"id":1},
   {"jsonrpc":"2.0","method":"server.remove","params":{"server":"24"},"id":2}
]

Response:

[
  {"jsonrpc":"2.0","result":{"status":"down"},"id":1}
  {"jsonrpc":"2.0","error":{"code":404,"message":"Server not found"},"id": 2}
]

In the id field, the API client can send anything so that after receiving responses from the server, match them with requests.

Also, the client can send “notifications” - requests without an “id” field that do not require a response from the server:

{"jsonrpc":"2.0","method":"analytics:trackView","params":{"type": "post", "id":"123"}}

Not so long ago I became acquainted with this protocol, but it is great for my tasks of creating an API on Laravel. To use such a protocol in your application, you need to set the dependency using the composer:

$ composer require sajya/server

All actions are described in Procedure classes, it is a familiar controller, but it must contain the static property name.

Create the following artisan class:

php artisan make:procedure TennisProcedure

A new file will be created in the app/Http/Procedures/TennisProcedure.php

Let's call the new procedure tennis, to do this, change the name property and add the pong returning value to the ping method to get this content:

namespace App\Http\Procedures;

use Sajya\Server\Procedure;

class TennisProcedure extends Procedure
{
    /**
     * The name of the procedure that will be
     * displayed and taken into account in the search
     */
    public static string $name = 'tennis';

    /**
     * Execute the procedure.
     *
     * @return string
     */
    public function ping(): string
    {
        return 'pong';
    }
}

Like the controller, the procedure needs to be registered in the routes file, define it in the file api.php:

use App\Http\Procedures\TennisProcedure;

Route::rpc('/v1/endpoint', [
    TennisProcedure::class
])->name('rpc.endpoint');

In order to turn to the required method, you must pass the name specified in the class and the necessary method with the delimiter "@" character. In our case, it will be: tennis@ping.

Let's make a curl call to the new API:

curl 'http://127.0.0.1:8000/api/v1/endpoint' --data-binary '{"jsonrpc":"2.0","method":"tennis@ping","params":[],"id" : 1}'

The result will be the resulting JSON string:

{"id":"1","result":"pong","jsonrpc":"2.0"}