Instruction Laravel Package

Getting Started

• Install the package and its wallet dependency first. This release expects Bavix Laravel Wallet to be present for wallet-enabled instruction items; run the wallet migrations before the package migrations.
• Publish and review the package migrations, then run php artisan migrate. Pay attention to columns storing price_minor and price-history records; these are the persistence foundation for the new pricing engine.
• Read the README sections on money handling rules and the architecture diagram before writing code. The important boundary is: models persist wallet state, services calculate pricing, DTOs serialize API output.
• Define your first priced instruction item using either a decimal string ('5.00') or an integer minor-unit value (500). Do not pass floats.
• First useful flow: create an instruction with priced items, attach or transact against the wallet, then read the resulting charge DTO. Confirm that the response exposes both price as a decimal string and price_minor as an integer.
• For API work, start from the charge and total DTOs rather than model attributes. They are the intended public representation of the new dual money format.

Implementation Patterns

• Treat minor units as the source of truth for computation. Use price_minor and total_amount_minor for sums, comparisons, discounts, and persistence; convert to decimal only at the API boundary.
• Keep human input and machine input explicit. Use decimal strings for forms, imports, and config authored by humans; use integers for seeders, factories, tests, and service-to-service payloads.
• Use Brick Money inside custom pricing logic instead of native arithmetic. Construct money from minor units and currency, perform operations with Brick Money, and serialize through the package DTOs.
• Let the pricing service own pricing rules. Avoid recalculating totals in controllers, API resources, or model accessors; call the package service and pass its DTO outward.
• When integrating wallet flows, create the wallet transaction and the instruction item revenue update in the same application flow. Use database transactions where your domain requires charge creation and wallet movement to succeed or fail together.
• Use price history as an audit trail. When changing an instruction item’s price, write through the package’s supported flow rather than updating the price column directly, so historical charges remain explainable.
• In API resources, preserve the dual representation exactly: cast price_minor and total_amount_minor to integers, and return price and total_amount as decimal strings. Do not let Eloquent or JSON casting silently turn decimal strings into floats.
• In tests, assert both representations. A useful assertion pattern is to verify the minor-unit total and then verify the decimal string output separately.
• For existing integrations, add a boundary adapter that accepts legacy float input, validates it, converts it to a decimal string or minor units once, and then calls the package. Keep that adapter outside the pricing service so the package remains float-free.

Gotchas and Tips

• The breaking change is real: floats are no longer supported. Search the codebase for float casts, (float) conversions, form requests accepting numeric values without validation, and seeders using 5.0. Replace them with '5.00' or 500.
• Do not mix representations in one calculation. Pick minor units for computation and convert only when producing API output. Mixing price and price_minor in the same sum is the quickest way to introduce rounding errors.
• Confirm the currency’s minor-unit exponent. The release notes use centavos as the example, which implies two decimal places, but wallet and pricing behavior should be verified for zero-decimal or three-decimal currencies before relying on a fixed 100 multiplier.
• Validate decimal strings before they reach the package. Empty strings, comma separators, localized formats, and trailing currency symbols should be normalized at the application boundary.
• Be careful with Eloquent casts. Casting price_minor to integer is appropriate; casting decimal price fields to float or decimal:2 can change the serialized type. Prefer explicit DTO/resource formatting.
• Wallet operations are not a replacement for pricing calculations. The wallet tracks balances and transactions; the pricing service determines what should be charged. Keep those responsibilities separate.
• Price history can grow quickly in write-heavy systems. Index lookups by instruction item and effective date, and avoid loading full history when only the current price is needed.
• When debugging totals, inspect the charge DTO before it is transformed by API resources. If price_minor is correct but price is wrong, the issue is usually serialization or a float cast rather than pricing logic.
• For extension, add custom pricing rules in the service layer rather than model events. The package’s separation of models, services, and DTOs is the intended seam for domain-specific pricing.
• If wallet transactions appear correct but instruction revenue does not, check that the wallet-enabled instruction item flow is being used and that revenue accumulation is triggered in the same transaction as the charge.