Forem: Orfeo

Making Object Properties Optional

Orfeo — Mon, 03 Nov 2025 17:42:17 +0000

Sometimes, you want to create types in TypeScript where not all properties must be provided. This makes your objects flexible, allowing you to specify only some properties when needed.

This tutorial shows how to define such types with optional properties, using a new CustomProperties example.

Original Type Definition

Here's an example of a type where all properties might be required and explicitly undefined:

export type CustomProperties = {
  language: Language | undefined,
  priority: "high" | "low" | undefined,
  archive: boolean | undefined,
}

This definition means you must always specify the properties, even if their value is undefined.

Making Properties Optional with `?`

To allow passing only some properties, mark properties as optional by adding a question mark (?) after the property name:

export type CustomProperties = {
  language?: Language,
  priority?: "high" | "low",
  archive?: boolean,
}

Key Points

The ? makes the property optional, so it can be omitted entirely.
You do not need to explicitly say | undefined because the property may be absent.
When present, the property's value must be one of the specified types.

Examples of Usage

const a: CustomProperties = { language: Language.fr };
const b: CustomProperties = { priority: "high", archive: false };
const c: CustomProperties = { language: Language.en, archive: true };
const d: CustomProperties = {}; // All properties omitted, valid!

Extending or Combining Types

If you need to add optional fields to an existing type, you can use intersection (&):

type BaseProperties = {
  type?: TMediaType,
  email_subject?: string,
  remote_id?: number,
};

export type ExtendedCustomProperties = BaseProperties & {
  language?: Language,
  priority?: "high" | "low",
  archive?: boolean,
};

This composes the base and new properties as optional.

Summary

Use ? to mark properties optional in type definitions.
Avoid | undefined for optional properties because optionality already allows absence.
Optional properties enable flexible object construction with any subset of the property keys.
Use intersection types to extend types easily with new optional properties.

References

Getting Random Enum Values in PHP Using Faker

Orfeo — Sat, 25 Oct 2025 13:00:01 +0000

In modern software development, creating realistic test data is indispensable for robust application testing and database seeding. PHP’s native enumeration feature, introduced in version 8.1, enhances type safety by restricting values to a defined set. This guide provides a formal, comprehensive explanation of how to leverage the Faker library to generate random enumeration values in PHP applications.

Prerequisites

This tutorial assumes familiarity with PHP 8.1 or later, given its native support for enums. Additionally, Composer should be configured in your development environment to manage Faker as a dependency.

Defining an Enum in PHP

The enumerated type in PHP is defined as follows. This example illustrates a Status enum with three possible string values:

enum Status: string {
    case Pending = 'pending';
    case Approved = 'approved';
    case Rejected = 'rejected';
}

This declaration imposes integrity on variables constrained to the Status type.

Installing and Configuring Faker

Faker, a widely adopted library for generating synthetic data, can be installed using Composer:

composer require fakerphp/faker

Create a Faker instance in your PHP script:

require_once 'vendor/autoload.php';

$faker = Faker\Factory::create();

Generating Random Enum Values with Faker

Two principal methods exist for producing random enum values via Faker:

Method 1: Supplying Enum Values Explicitly to `randomElement()`

By enumerating the enum values as an array, Faker’s randomElement() can be applied directly:

$randomStatus = $faker->randomElement([
    Status::Pending->value,
    Status::Approved->value,
    Status::Rejected->value,
]);

echo $randomStatus; // Outputs: 'pending', 'approved', or 'rejected'

Method 2: Passing the Enum Class to `randomElement()`

Current versions of Faker support passing the enum class itself to randomElement(), which internally extracts all possible cases:

$randomStatus = $faker->randomElement(Status::class);

echo $randomStatus->value; // Outputs one of the corresponding enum values

This method offers a streamlined approach and greater maintainability, especially when enum cases evolve.

Integration in Laravel Factories

For Laravel developers, Faker’s enum value generation can be seamlessly incorporated into model factories:

public function definition(): array
{
    return [
        'status' => $this->faker->randomElement(Status::cases()),
    ];
}

This practice ensures test and seed data accurately reflect application constraints.

Conclusion

The combination of PHP’s native enums and Faker’s flexible data generation facilities significantly elevates the quality and reliability of test data. Employing the described methods enhances type safety and development efficiency.

Developers are encouraged to adopt these techniques to maintain consistency in their data models and foster improved application robustness.

Simplifying Async Function Definitions in TypeScript

Orfeo — Sat, 25 Oct 2025 10:10:44 +0000

When working with asynchronous code in TypeScript, you usually define functions like this:

function complete(event: AutoCompleteCompleteEvent) {
  // Your code
}

However, you can also define the same function as an async arrow function expression, which can be useful when assigning functions as values or passing them as props, callbacks, or event handlers.

Here’s how that looks:

const complete = (event: AutoCompleteCompleteEvent) => {
  // Your code
};

Async version:

const complete = async (event: AutoCompleteCompleteEvent) => {
  // Your code
};

Notice the differences:

No function keyword — you use an arrow (=>) instead.
The async keyword stays before the parameter list.
This pattern allows you to define asynchronous handlers inline or as part of an object or class property.

This syntax is particularly handy in frameworks like React or Vue where you often need to bind methods to components or use closures. It keeps your function definitions compact and consistent with modern JavaScript style.

Add composer package using path for local development

Orfeo — Sat, 11 Oct 2025 16:34:09 +0000

Testing a Local Laravel Package with Composer Path Repositories

When developing a custom Laravel package, you might want to test it inside another Laravel project without publishing it to Packagist. Composer allows this with the path repository type, which creates a symlink to your package instead of copying it.

This way, any changes you make to the package’s files are instantly available in your testing project.

1. Add the Local Package Repository

In your Laravel project (the consumer project), tell Composer where your local package is located.

Run:

composer config repositories.local '{"type": "path", "url": "/absolute/path/to/my-dev-package"}' --file composer.json

Replace /absolute/path/to/my-dev-package with the full path to your package’s root folder.
This adds a repositories entry to your composer.json for the given path.

2. Require the Package

Install your package into the consumer project:

composer require my/dev-package

Use the same name defined in your package’s composer.json under "name": "my/dev-package".
Composer will create a symlink so changes in your package source are reflected immediately.

3. Work on the Package in Real Time

Since this is a symlink, you can:

Edit files in /absolute/path/to/my-dev-package
Refresh or run your Laravel project
See changes instantly without reinstalling the package

4. Optional: Use “version” for Better Control

If your package composer.json contains a "version" key (e.g., "version": "1.0.0") or uses a dev-branch version, Composer can handle updates more gracefully.

Example for a development branch:

"version": "dev-main"

Then require:

composer require my/dev-package:dev-main

5. When Ready to Publish

Once your package is stable, you can:

Remove the path repository from composer.json
Require it from Packagist or your private VCS repository

How to Test File Uploads in Laravel and Pest Without Faking Files

Orfeo — Fri, 10 Oct 2025 12:15:49 +0000

When writing tests in Laravel, the simplest way to simulate a file upload is by using the UploadedFile::fake() helper:

$file = UploadedFile::fake()->image('avatar.png');

$mediaResponse = post('/api/user_media/upload', ['media' => $file])->assertStatus(200)

This works well for basic scenarios, but sometimes we need to test with real files—such as oversized images or files with invalid content—to verify how our application handles them.

To upload a specific file stored in your test directory, you can create an UploadedFile instance manually:

// UploadedFile will move the file
Storage::copy('test/mail-test.docx', 'tmp/mail-test.docx');

$filename = 'too-large.png';
$uploadedFile = new UploadedFile(
    storage_path("app/private/tmp/$filename"),
    $filename,
    test: true,
);

This approach allows you to use an actual file from your storage for more realistic and edge-case testing.

Include product body field in Shopify drawer search

Orfeo — Mon, 06 Oct 2025 06:24:58 +0000

Introduction

Many themes don’t include the body field as part of the search condition in the drawer (the search that appears when clicking the search icon in the top-right corner).

In some cases, you may want to include the body field in search results.

Solution

Before making any changes, it’s highly recommended to create a backup copy of your theme by clicking the Duplicate button.

Go to Online Store → Themes, and on your current theme, click Edit code:

Next, search for the term "resources[options][fields]" in your theme’s files. This is often found inside a file like search.js.

For example, you might see a line like this:

url.searchParams.set('resources[options][fields]', 'title,product_type,variants.title,variants.barcode');

Modify it to include the body field:

url.searchParams.set('resources[options][fields]', 'title,product_type,variants.title,body,variants.barcode');

Testing

Finally, test the search feature to ensure it works as expected.

If you encounter any issues (such as the drawer not opening or no results appearing), check the browser’s developer console for JavaScript errors or inspect the network requests and responses.

Using @mixin for referencing in traits in PHP (Laravel example)

Orfeo — Mon, 06 Oct 2025 06:24:41 +0000

When building modular PHP applications, traits are a great way to keep your code organized and reusable. Let’s walk through an example showing how to make your editor and static analysis tools fully understand the connection between a trait and a model.

Step 1: The problem

Let’s say you have a Document model with a toPdf() method. To make your model more maintainable, you extract the PDF generation logic into a trait called DocumentPdfTrait.

But when working in VS Code with PHP Intelephense, you notice that inside the trait, the editor doesn’t recognize the model’s properties or methods:

trait DocumentPdfTrait
{
    public function toPdf(): string
    {
        // $this->title belongs to Document model
        $title= $this->title; // IDE: “Undefined property: title”
        $body = $this->getBody(); // No autocomplete or navigation
        return PdfGenerator::generateToTmpPath($title, $body);
    }
}

You lose autocompletion, “Go to definition,” and type checking—all crucial for avoiding errors in large projects.

Step 2: The solution — using `@mixin`

To fix this, add a DocBlock with the @mixin annotation above your trait. This tells your IDE and static analyzers that the trait behaves as if it’s part of the Document model.

/**
 * @mixin \App\Models\Document
 */
trait DocumentPdfTrait
{
    public function toPdf(): string
    {
        $title = $this->title;
        $body = $this->getBody()
        return PdfGenerator::generateToTmpPath($title, $body);
    }
}

Step 3: The result in your editor

Once you add this line:

Autocomplete recognizes all model attributes and methods.
Function navigation (Go to Definition) starts working again.
Error detection improves—for example, calling an undefined method will trigger a warning.

Your editor now treats the trait’s code as though it were written inside the Document class itself.

Step 4: Static analysis tools (PHPStan, Psalm)

The @mixin annotation isn’t just helpful for IDEs—it also improves static analysis results in tools like PHPStan and Psalm.

Without @mixin, these tools may report “undefined property” or “undefined method” errors inside your trait. After adding the annotation:

PHPStan and Psalm correctly infer the available methods and attributes from the Document model.
False positives are greatly reduced, especially in complex Laravel projects.
You maintain strict type safety while keeping your code modular.

If you’re running PHPStan, for example, running:

vendor/bin/phpstan analyse

will now pass cleanly for your trait without any “undefined” warnings.

This makes @mixin a small but powerful tool for ensuring that your codebase stays clean, navigable, and statically analyzable—even when splitting functionality across multiple traits.

Writing a Shopify A-Z brands page

Orfeo — Mon, 06 Oct 2025 05:38:04 +0000

Introduction

In this tutorial, you’ll learn how to write a simple Liquid snippet that generates a page listing all brands, grouped and sorted by their first character.

Structure

Suppose you manage a website featuring car brands and want to display all brands grouped alphabetically. When a user clicks a brand, they should be redirected to its corresponding collection page.

To achieve this, we’ll create individual collections for each brand and use a custom metafield called abc_collection to filter only the relevant ones.

Model setup

Open Settings → Metafields and Metaobjects.
Navigate to Collections.
Add a definition for "ABC collection" of type "True or false":

We will use this attribute to get all the ABC collections.

Content setup

Create each brand collection and set field "ABC collection" to true. You will filter products using "conditions". The following is an example for all cars with Vendor (brand) BMW:

Theme setup

Go to Online Store → Themes → Customize.
From the top navigation, open the Pages section, then click Create a template. Name it AZ collection.
In the left sidebar, add a Custom Liquid block. On the right side, we will later insert our Liquid code.

Create the page

Under Online Store → Pages, create a new page and assign it the AZ collection template.

The code

In this case we use Tailwind theme. The classes should be changedbased on the CSS framework used (or you can write the CSS classes).

{% assign sorted_collections = collections | sort: 'title' %}

{% assign current_letter = '' %}

<div class="page-width grid-list products-list f-grid md:f-grid-3-cols xl:f-grid-3-cols f-grid-2-cols f-grid--gap-medium">
  {% for collection in sorted_collections %}
    {% if collection.metafields.custom.abc_collection != true %}
      {% continue %}
    {% endif %}

    {% assign first_letter = collection.title | slice: 0, 1 | upcase %}

    {% if first_letter != current_letter %}
      {% if current_letter != '' %}
        </div>
      {% endif %}
      <div class="f-column">
        <h3 style="margin-bottom: 1em;">{{ first_letter }}</h3>

        {% assign current_letter = first_letter %}
    {% endif %}

    <div style="margin-bottom: 0.5em;">
      <a href="{{ collection.url }}">{{ collection.title }}</a>
    </div>

    {% if forloop.last %}
      </div>
    {% endif %}
  {% endfor %}
</div>

Sorting adjustment

To ensure collections with uppercase titles don’t appear last, replace the sort method:

{% assign sorted_collections = collections | sort_natural: 'title' %}

Adding tags

You can enhance the collections with descriptive tags by using metafields.

Under Settings → Metafields and Metaobjects → Collections, create a metafield definition for tags:

Now add few tags:

We add again a new collection metafield definition for the tags on the collection referring to the tags (Metaobject, List of entries):

Now assign tags to the collections.

Code with tags

Include the following Liquid code to display tags next to each brand:

We could make multiple AZ pages by filtering on a tag. Each tag can have multiple tags (eg. Family, Luxury, Japanse) and we can provide for each tag a page.

{% assign sorted_collections = collections | sort_natural: 'title' %}

{% assign current_letter = '' %}

<div class="page-width grid-list products-list f-grid md:f-grid-3-cols xl:f-grid-3-cols f-grid-2-cols f-grid--gap-medium">
  {% for collection in sorted_collections %}
    {% if collection.metafields.custom.abc_collection != true %}
      {% continue %}
    {% endif %}

    {% assign first_letter = collection.title | slice: 0, 1 | upcase %}

    {% if first_letter != current_letter %}
      {% if current_letter != '' %}
        </div>
      {% endif %}
      <div class="f-column">
        <h3 style="margin-bottom: 1em;">{{ first_letter }}</h3>

        {% assign current_letter = first_letter %}
    {% endif %}

    <div style="margin-bottom: 0.5em;">
      <a href="{{ collection.url }}">{{ collection.title }}</a>

      <span class="abc-tag-list">
        {% for tag in collection.metafields.custom.abc_tags.value %}
          <span class="abc-tag">
            {{ tag.name }}
          </span>
        {% endfor %}
      </span>
    </div>

    {% if forloop.last %}
      </div>
    {% endif %}
  {% endfor %}
</div>

This will display the tags next to the brand names.

Add the following CSS under Custom CSS for tag styling:

.abc-tag {
  color: #6c757d;
  font-size: .9em;
  margin-left: .1em;
}

Group by tag

You could also make multiple pages filtering products of only a specific tag (here tag "Italian" with page title "Italian"):

{% assign sorted_collections = collections | sort_natural: 'title' %}

{% assign current_letter = '' %}
{% assign tag_name = 'Italian' %}

<div class="page-width grid-list products-list f-grid md:f-grid-3-cols xl:f-grid-3-cols f-grid-2-cols f-grid--gap-medium">
  {% for collection in sorted_collections %}
    {% if collection.metafields.custom.abc_collection != true %}
      {% continue %}
    {% endif %}

    {% assign found = false %}
    {% for tag in collection.metafields.custom.abc_tags.value %}
      {% if tag.name == tag_name %}
        {% assign found = true %}
        {% break %}
      {% endif %}
    {% endfor %}

    {% if found == false %}
      {% continue %}
    {% endif %}

    {% assign first_letter = collection.title | slice: 0, 1 | upcase %}

    {% if first_letter != current_letter %}
      {% if current_letter != '' %}
        </div>
      {% endif %}
      <div class="f-column">
        <h3 style="margin-bottom: 1em;">{{ first_letter }}</h3>

        {% assign current_letter = first_letter %}
    {% endif %}

    <div style="margin-bottom: 0.5em;">
      <a href="{{ collection.url }}">{{ collection.title }}</a>

      <span class="abc-tag-list">
        {% for tag in collection.metafields.custom.abc_tags.value %}
          <span class="abc-tag">
            {{ tag.name }}
          </span>
        {% endfor %}
      </span>
    </div>

    {% if forloop.last %}
      </div>
    {% endif %}
  {% endfor %}
</div>

Tip

Write your code in Visual Studio Code using the Shopify Liquid extension:

Auto-formatting is also supported.

Forem: Orfeo

Making Object Properties Optional

Original Type Definition

Making Properties Optional with ?

Key Points

Examples of Usage

Extending or Combining Types

Summary

References

Getting Random Enum Values in PHP Using Faker

Prerequisites

Defining an Enum in PHP

Installing and Configuring Faker

Generating Random Enum Values with Faker

Method 1: Supplying Enum Values Explicitly to randomElement()

Method 2: Passing the Enum Class to randomElement()

Integration in Laravel Factories

Conclusion

Simplifying Async Function Definitions in TypeScript

Add composer package using path for local development

Testing a Local Laravel Package with Composer Path Repositories

1. Add the Local Package Repository

2. Require the Package

3. Work on the Package in Real Time

4. Optional: Use “version” for Better Control

5. When Ready to Publish

How to Test File Uploads in Laravel and Pest Without Faking Files

Include product body field in Shopify drawer search

Introduction

Solution

Testing

Using @mixin for referencing in traits in PHP (Laravel example)

Step 1: The problem

Step 2: The solution — using @mixin

Step 3: The result in your editor

Step 4: Static analysis tools (PHPStan, Psalm)

Writing a Shopify A-Z brands page

Introduction

Structure

Model setup

Content setup

Theme setup

Create the page

The code

Sorting adjustment

Adding tags

Code with tags

Group by tag

Tip

Making Properties Optional with `?`

Method 1: Supplying Enum Values Explicitly to `randomElement()`

Method 2: Passing the Enum Class to `randomElement()`

Step 2: The solution — using `@mixin`