README

English | 中文

A Symfony bundle for managing freight templates in e-commerce applications. This bundle provides a complete solution for handling shipping cost calculations and template management.

Features

Freight template management with validation
Multiple delivery types and valuation methods
EasyAdmin integration for backend management
Doctrine ORM integration with proper entity mapping
RESTful API support
Comprehensive validation and constraints
Fixtures for development testing

Requirements

PHP 8.1+
Symfony 6.4+
Doctrine ORM
EasyAdmin Bundle

Installation

Install the bundle

composer require tourze/freight-template-bundle

Register the bundle

The bundle should be automatically registered by Symfony Flex. If not, add it to config/bundles.php:

return [
    // ...
    Tourze\FreightTemplateBundle\FreightTemplateBundle::class => ['all' => true],
];

Run database migrations

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

Load demo fixtures (optional)

php bin/console doctrine:fixtures:load --append --group=FreightTemplate

Usage

Service Usage

use Tourze\FreightTemplateBundle\Service\FreightTemplateService;

class YourService
{
    public function __construct(
        private FreightTemplateService $freightTemplateService
    ) {}

    public function calculateShipping(string $templateId): ?FreightTemplate
    {
        // Find freight template by ID
        return $this->freightTemplateService->findValidTemplateById($templateId);
    }

    public function getAvailableTemplates(): array
    {
        // Get all valid freight templates
        return $this->freightTemplateService->findAllValidTemplates();
    }
}

Entity Usage

use Tourze\FreightTemplateBundle\Entity\FreightTemplate;
use Tourze\FreightTemplateBundle\Enum\FreightValuationType;
use Tourze\ProductCoreBundle\Enum\DeliveryType;

$template = new FreightTemplate();
$template->setName('Standard Shipping');
$template->setDeliveryType(DeliveryType::EXPRESS);
$template->setValuationType(FreightValuationType::FIXED);
$template->setCurrency('CNY');
$template->setFee('15.00');
$template->setValid(true);

API Reference

FreightTemplateService

Method	Parameters	Return Type	Description
`findValidTemplateById()`	`string $templateId`	`?FreightTemplate`	Find valid template by ID
`findAllValidTemplates()`	-	`array<FreightTemplate>`	Get all valid templates
`findTemplatesBySpuIds()`	`array $spuIds`	`array<FreightTemplate>`	Find templates by SPU IDs

FreightTemplate Entity

Main Properties

id: string - Unique identifier (Snowflake ID)
name: string - Template name
deliveryType: DeliveryType - Delivery method
valuationType: FreightValuationType - Valuation method
currency: string - Currency code (default: CNY)
fee: string - Shipping fee
valid: bool - Whether template is active
sortNumber: int - Sort order
createTime: DateTime - Creation timestamp
updateTime: DateTime - Last update timestamp

Enums

DeliveryType (配送方式)

EXPRESS - Express delivery
PICKUP - Self pickup
STANDARD - Standard delivery
ECONOMY - Economy delivery

FreightValuationType (计费方式)

FIXED - Fixed fee
BY_ITEM - Per item billing

Admin Interface

Access the freight template management interface at /admin/product/freight-template:

Create and edit freight templates
Configure delivery types and valuation methods
Manage template validity and sorting
Filter and search templates

Testing

# Run all tests
./vendor/bin/phpunit packages/freight-template-bundle/tests

# Run PHPStan analysis
php -d memory_limit=2G ./vendor/bin/phpstan analyse packages/freight-template-bundle

Dependencies

tourze/product-core-bundle - Core product functionality
tourze/doctrine-*-bundle - Doctrine integration bundles
easycorp/easyadmin-bundle - Admin interface
tourze/easy-admin-enum-field-bundle - Enum field support for EasyAdmin

Configuration

The bundle works out of the box with minimal configuration. However, you can customize certain aspects:

# config/packages/freight_template.yaml
freight_template:
    default_currency: 'CNY'
    default_valuation_type: 'fixed'

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

License

MIT License

tourze / freight-template-bundle

Maintainers

Details