Azure Table Service Bundle Laravel Package

Getting Started

• Install with composer require attek/azure-table-bundle, then publish/configure the connection settings (account name, account key, and optionally a custom endpoint for Azurite). The bundle reads these from config rather than env directly, so wire your .env values into the package config on first install.
• Look here first: the bundle's DI configuration (service definitions and the table-client factory) and the client wrapper class — that wrapper is what you'll actually inject. Everything else (entity serialization, query helpers) hangs off it.
• Symfony-in-Laravel caveat: this is a Symfony bundle. In a Laravel app you generally do not register the bundle; instead pull the underlying client out of the container manually (or bind the wrapper class as a singleton in a Laravel service provider). Budget 15 minutes for that wiring before your first write.
• First use case: a low-ceremony append-only store — audit events, feature flags, or session/device state keyed by PartitionKey/RowKey. Create the table once at deploy time, then insert a single entity and read it back by point query to confirm connectivity and auth.

Implementation Patterns

• Wrap the client in a repository per table. Don't inject the raw client into controllers; expose intent methods (recordEvent, findByDevice, setFlag). This is where you centralise partition-key construction and keeps OData filter strings out of your app code.
• Partition-key design is the whole game. Use a composite like tenant:{id} or date:{yyyy-MM} so point and range queries stay single-partition. Partition-per-tenant gives you scalable scans; partition-per-day gives you cheap time-range reads and easy truncation.
• Query by key, not by property. Point queries (PartitionKey eq X and RowKey eq Y) are the fast path; range queries on RowKey are next. Property filters scan the partition and get expensive fast — treat them as reporting, not request-path.
• Batch writes: group inserts/updates/deletes into a single transaction when they share a partition (see limits below). This is the main throughput lever and the main source of surprising failures.
• Optimistic concurrency: read the entity, keep its ETag, and send it back on update. On conflict you get a precondition failure — retry with a re-read rather than blindly overwriting.
• Error handling (v1.1.2): the release adds error-code checking, so branch on the Azure error code rather than sniffing exception messages. Map the codes you care about (TableAlreadyExists, EntityAlreadyExists, UpdateConditionNotSatisfied, ResourceNotFound) to your own domain exceptions in the repository layer; let everything else bubble.
• Testing: run Azurite in CI and point the endpoint config at it. Keep a createTableIfMissing helper in test setup so suites are order-independent. Assert on error codes, not messages, so the tests survive SDK upgrades.

Gotchas and Tips

• No cross-partition transactions. Batch operations require all entities to share a partition key and the same operation type. Splitting a mixed write set is on you.
• Batch cap is 100 entities and every entity counts toward the payload limit — chunk before sending.
• Paging is not automatic. Large result sets return a continuation token; loop until it's null or you'll silently truncate at the service page size. Cap the loop and log when you hit it.
• Escape OData literals yourself. Single quotes in filter values must be doubled, and strings need quoting. Build filters through a small helper — hand-concatenated filters are the most common source of 400s.
• Dates must be UTC with no offset. A local-timezone DateTime will either be rejected or shift silently. Normalise at the repository boundary.
• Property limits are hard: 64 KB per property, ~1 MB per entity, 252 properties, and no nested objects — flatten before insert. Table names are 3–63 alphanumeric characters and can't start with a digit.
• Throttling is real. Under load Azure returns 429/503 with a Retry-After; the client does not retry for you. Add jittered exponential backoff around writes, and consider making it a shared middleware/trait so every repository inherits it.
• v1.1.2 error-code checking is the extension point to lean on. If you'd previously matched on message text (or on generic "request failed" exceptions), migrate those branches to the code now — it's the stable contract. Anything still matching strings will break on the next SDK bump.
• No migrations, but you still need versioning. The store is schemaless, so old rows won't gain new properties. Add a schema-version property and handle missing fields defensively on read.
• Emulator parity isn't perfect. Azurite is close but not identical for some auth and continuation-token edge cases; smoke-test anything query-heavy against a real storage account before shipping.