Sylius: Doc's code examples are not up to date for custom calculators

[rmNyro]

Hi everyone,

After many trials and "errors" I've finally made my first custom calculator and found out I was fighting against the doc which is not up to date (at least code samples, the text seems coherent). For instance :

<?php

// src/Acme/ShopBundle\Shipping/DHLCalculator.php

namespace Acme\ShopBundle\Shipping;

use Acme\ShopBundle\Shipping\DHLService;
use Sylius\Bundle\ShippingBundle\Calculator\Calculator;
use Sylius\Bundle\ShippingBundle\Model\ShippingSubjectInterface;

class DHLCalculator extends Calculator
{
    private $dhlService;

    public function __construct(DHLService $dhlService)
    {
        $this->dhlService = $dhlService;
    }

    public function calculate(ShippingSubjectInterface $subject, array $configuration)
    {
        return $this->dhlService->getShippingCostForWeight($subject->getShippingWeight());
    }
}

should be implementing CalculatorInterface instead of Calculator which I supposed was refactored. The same code, but working now (at least in beta-1, I'll be testing in beta-2 for a possible bug and will post about this too) should look like :

<?php

// src/Acme/ShopBundle\Shipping/DHLCalculator.php

namespace Acme\ShopBundle\Shipping;

use Acme\ShopBundle\Shipping\DHLService;
use Sylius\Component\Shipping\Calculator\CalculatorInterface;
use Sylius\Component\Shipping\Model\ShipmentInterface;

final class DHLCalculator implements CalculatorInterface
{
    private $dhlService;

    public function __construct(DHLService $dhlService)
    {
        $this->dhlService = $dhlService;
    }

    public function calculate(ShippingSubjectInterface $subject, array $configuration)
    {
        return $this->dhlService->getShippingCostForWeight($subject->getShippingWeight());
    }

    public function getType()
    {
        return 'dhl';
    }
}

It's the same story for the rest of the page, every example seems broken. But again the text seems coherent... A bonus would also be to have a YAML version of the service declaration examples (as it's hard for a newbie to translate).
BTW I don't quite get why there's so much XML aside with YAML. But it has nothing to do with the rest, I'm just curious.

Keep up the good work. :)

[lchrusciel]

Thanks for reporting. Are you willing to open a PR with fixes for that?

According to your question, XML is an old style of docs reference I suppose. Every new thing which was written by @CoderMaggie has a YAML reference. We should probably unify this at some point.

[johnrisby]

Is anyone working on updating the documentation? I'm importing old orders and need to set a custom shipping price (ideally without using adjustments). I thought a shipping calculator that could work it out based on the historic price stored in the order would work but I've just wasted a few hours trying to create a calculator based on this out-dated documentation.

[lchrusciel]

@johnrisby not at the moment I'm afraid 😢

[johnrisby]

That's a real shame. I'm loving working with Sylius but I'm hitting problems on a daily basis because of the documentation.

Please take this the right way - I love Sylius and releasing v1.0.0 stable was a great achievement that the core team and all contributors should be very proud of it.

BUT... documentation is vital and I'm really surprised it's so out of date, especially as one of the core principals of Sylius is clean, tested, code. Surely that philosophy should naturally extend to the documentation. In fact, the cleaner it is, the less documentation is needed. But it does need some, with working examples, and it needs to be up-to-date.

I've raised this on Slack a few times and had comments along the lines of 'you can always update the documentation yourself'. That's true. But only when I finally get things working, and by then I'm behind on what I'm doing.

If a volunteer can't be found (or a team of volunteers) to update it, Sylius themselves should really put a member of the core team on it full time.

Now we're at a stable release, it's time to start attracting people who are not expecting to have to dig into the source code to find out why the examples don't work. The more people that find it now, with this standard of documentation, the more will leave frustrated and probably never return. And that would be a real loss for Sylius and for them.

I will do my bit when I can, but that will be too late for many I think.

Please take this in the spirit it is intended.

[pjedrzejewski]

@johnrisby Thank you John for your comment and we take it the way intended. :) I hope to allocate some time to docs soon to fix these outdated articles. 👍

[johnrisby]

Thanks Paweł ;)