IBX-9680: Extending discounts

[mnocon]

Things added:

1. Example how to deal with discounts products using the API:

• resolving prices of discounted products and retrieving the applied discounts
• retrieving discount information from orders

Preview:

• https://ez-systems-developer-documentation--2936.com.readthedocs.build/en/2936/discounts/discounts_api/

2. Extending:

• custom condition
• custom rule
• extending the form:
• adding a custom step and integrating a custom condition
• adding a custom rule

Previews:

• https://ez-systems-developer-documentation--2936.com.readthedocs.build/en/2936/discounts/extend_discounts/
• https://ez-systems-developer-documentation--2936.com.readthedocs.build/en/2936/discounts/extend_discounts_wizard/

3. Enhanced price resolving descirption to include discounts
4. Small changes around the the discount docs, like improving the main discounts card page.

[github-actions]

Preview of modified files

Preview of modified Markdown:

• docs/api/event_reference/discounts_events.md
• docs/commerce/order_management/order_management_api.md
• docs/discounts/discounts.md
• docs/discounts/discounts_api.md
• docs/discounts/extend_discounts.md
• docs/discounts/extend_discounts_wizard.md
• docs/permissions/policies.md
• docs/pim/price_api.md
• docs/search/discounts_search_reference/discounts_criteria.md
• docs/search/discounts_search_reference/discounts_sort_clauses.md

[mnocon]

Experimental, please let me know what you think - I'm ok with removing this as well

[mnocon]

I wanted to include the code in two shapes - first only for creating form (Step1) and then in its full form (Step2)

The Step1/Step2 can be confusing because it's not related to wizard steps, but to given example steps.

[konradoboza]

Great work! I reviewed mostly part related to extending API, I will let Paweł check extending the discount wizard. A few remarks:

[Steveb-p]

In general, whenever additional data might be needed for Discount condition/rule, it is heavily suggested to use data loaded on demand, by a function call.

Providing variable to expression engine means that it will be loaded always, regardless if the variable is actually needed for resolution or not.

I would rather suggest making this a function available within the engine. It could even use caching to ensure it's not loaded more than once.

[mnocon]

Super valuable feedback, thank you! I've focused on the "how" and missed the "why".

I've added a note about variables vs functions: 6742514 (without rewriting the example, I hope that's ok)

[Steveb-p]

Cool concept, but it won't work for leap years - this code breaks on 29th of february :)

[mnocon]

I don't see how, could you please elaborate?

The reference year is set to 2000, which is a leap year - on 29.02 it boils down to:

php > $date = \DateTimeImmutable::createFromFormat('Y-m-d', '2000-02-29');
php > var_dump($date);
object(DateTimeImmutable)#1 (3) {
  ["date"]=>
  string(26) "2000-02-29 17:22:05.000000"
  ["timezone_type"]=>
  int(3)
  ["timezone"]=>
  string(3) "UTC"
}

I don't think it should break on leap years.

[Steveb-p]

I've used the following code to check.

<?php

final class IsAnniversaryResolver
{
    private const YEAR_MONTH_DAY_FORMAT = 'Y-m-d';

    private const MONTH_DAY_FORMAT = 'm-d';

    private const REFERENCE_YEAR = 2000;

    public function __invoke(DateTimeInterface $date, int $tolerance = 0): bool
    {
        $d1 = $this->unifyYear(new DateTimeImmutable('2025-03-01 12:00:00'));
        // Below does not work either
        // $d1 = $this->unifyYear(new DateTimeImmutable('2025-02-29 12:00:00'));
        $d2 = $this->unifyYear($date);

        $diff = $d1->diff($d2, true);

        // Check if the difference between dates is within the tolerance
        return $diff->days <= $tolerance;
    }

    private function unifyYear(DateTimeInterface $date): DateTimeImmutable
    {
        // Create a new date using the reference year but with the same month and day
        $newDate = DateTimeImmutable::createFromFormat(
            self::YEAR_MONTH_DAY_FORMAT,
            self::REFERENCE_YEAR . '-' . $date->format(self::MONTH_DAY_FORMAT)
        );

        if ($newDate === false) {
            throw new RuntimeException('Failed to unify year for date.');
        }

        return $newDate;
    }
}

$resolver = new IsAnniversaryResolver();

var_dump($resolver->__invoke(new DateTime('2024-02-29 00:00:00')));
// bool(false)
var_dump($resolver->__invoke(new DateTime('2026-02-29 00:00:00')));
// bool(true)

Basically, 2024-02-29 gets anniversaries only every leap year.

[mnocon]

Right, TBH I'm not sure I'd treat 29-02 accounts in "real" implementation, would need a good spec from PM and lots of tests 😄 Probably would extend it to "anniversary week" to make the problem simpler.

I've added a note mentioning the naive approach of this implementation in e105acb , to make the reader aware of the shortcuts taken.

[adriendupuis]

I would use <nobr> also on the last column. For example with this one, I would also try to not have the coma alone at the start of a new line:

Suggested change

	| <nobr>`IsValidDiscountCode`</nobr> | Cart | <nobr>`is_valid_discount_code`</nobr> | Checks if the correct discount code has been provided and how many times it was used by the customer | `discount_code`, `usage_count` |
	| <nobr>`IsValidDiscountCode`</nobr> | Cart | <nobr>`is_valid_discount_code`</nobr> | Checks if the correct discount code has been provided and how many times it was used by the customer | <nobr>`discount_code`,</nobr> <nobr>`usage_count`</nobr> |

[mnocon]

Thank you 😄 Your comment made me refactor the tables a bit - I've made the identifier a part of the first column, making it much more readable: 85aa5da

[adriendupuis]

It's really good to have the table below. But, is there a way for a developer to find those priorities by oneself? To be able to also find the already created custom ones would be great.

[mnocon]

I don't see a way of doing this by inspecting the service container, I think the only solution is to:

1. Subscribe to the CreateFormDataEvent and MapDiscountToFormDataEvent events
2. Inspect (with a debugger?) the return value of $event->getData->getSteps()

Unless someone just reads the source code, but that's a lazy answer (always true).

Unless @Steveb-p you can think of a way of doing this?

[adriendupuis]

Oh, you're right, the priority is not on the listener but in its data…
php bin/console debug:event-dispatcher MapDiscountToFormDataEvent is useless here.

[adriendupuis]

By building a fake event, I can get the custom steps applied:

<?php

declare(strict_types=1);

namespace App\Command;

use DateTime;
use Ibexa\Bundle\Discounts\Form\Data\Conditions;
use Ibexa\Bundle\Discounts\Form\Data\DiscountValue\FixedAmountDiscountValue;
use Ibexa\Bundle\Discounts\Form\Data\EditDiscountData;
use Ibexa\Bundle\Discounts\Form\Data\GeneralProperties;
use Ibexa\Bundle\Discounts\Form\Data\ProductCondition;
use Ibexa\Bundle\Discounts\Form\Data\UserCondition;
use Ibexa\Contracts\Core\Repository\Repository;
use Ibexa\Contracts\Core\Repository\Values\Content\Language;
use Ibexa\Contracts\Discounts\Event\MapDiscountToFormDataEvent;
use Ibexa\Discounts\Value\Discount\Discount;
use Ibexa\Discounts\Value\DiscountRule\FixedAmount;
use Psr\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(name: 'app:discounts_step_event_debug', description: 'Hello PhpStorm')]
class DiscountsStepEventDebugCommand extends Command
{
    public function __construct(private EventDispatcherInterface $dispatcher, private Repository $repository)
    {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $user = $this->repository->getUserService()->loadUser($this->repository->getPermissionResolver()->getCurrentUserReference()->getUserId());

        $now = new DateTime();

        $discount = new Discount(0, 'debug', 'cart|catalog', 0, false,
            $now, $now, $now, $user, $user, new FixedAmount(null), [], null, null);

        $editDiscountData = new EditDiscountData($discount, new GeneralProperties(new Language()),
            new UserCondition(), new ProductCondition(), new Conditions(), new FixedAmountDiscountValue());

        $event = new MapDiscountToFormDataEvent($editDiscountData, $discount);

        foreach ($this->dispatcher->getListeners(MapDiscountToFormDataEvent::class) as $listener) {
            call_user_func($listener, $event);
        }

        foreach ($event->getData()->getSteps() as $step) {
            $output->writeln(sprintf('%s (priority: %d)', $step->getIdentifier(), $step->getPriority()));
        }

        return Command::SUCCESS;
    }
}

% php bin/console app:discounts_step_event_debug
general_properties (priority: 50)
target_group (priority: -20)
products (priority: -30)
discount_value (priority: -50)
summary (priority: -1000)