Swift Bundle Laravel Package

Getting Started

This bundle wraps a pure-PHP OpenStack Swift client in Symfony services, so its only job is to let you authenticate to a Swift endpoint and read/write blobs in a container without juggling curl or the OpenStack SDK directly.

1. Install: composer require treehouselabs/swift-bundle — note the last tagged release is from April 2015, so expect a Symfony 2.x/3.0-era AppKernel.php registration (new TreeHouse\SwiftBundle\TreeHouseSwiftBundle()) rather than Symfony Flex auto-wiring.
2. Look here first: open the bundle's DependencyInjection/Configuration.php and Resources/config/services.yml. That tells you the exact config keys (auth URL, tenant, username, password, default container) and the service IDs you will inject. There is effectively no documentation beyond the README, so the DIC definition is the API.
3. Configure something like:

   tree_house_swift:
       auth_url: "%swift.auth_url%"
       username: "%swift.username%"
       password: "%swift.password%"
       tenant:   "%swift.tenant%"
       container: "%swift.container%"
   

4. First use case: store a user-uploaded file. Inject the bundle's client service into a controller/service and call upload-style methods with a container name, object key, and a stream or string of bytes, then read it back with a download/readObject call and stream it to StreamedResponse.

Implementation Patterns

• Inject the client, not the bundle. The bundle exposes a connection/client service (and possibly a container-specific helper). Type-hint against the underlying TreeHouse\Swift\* client class from the dependency library so your application code survives if the bundle is ever replaced by direct SDK usage.
• Write a thin application-level storage service. Wrap the Swift client in your own ObjectStore interface with put($key, $stream, array $headers), get($key), delete($key), exists($key). This is the single most valuable pattern with this package, because the bundle is thin and you will want to swap it out or fall back to local storage in tests.
• Stream everything. Swift is an object store; never file_get_contents a large object into memory. Upload from a stream resource and expose downloads via Symfony's StreamedResponse with the object's Content-Type and Content-Length headers copied over.
• Use containers per concern (e.g. user-uploads, exports, temp) and map each to a config-driven container name, so environment promotion (dev/staging/prod Swift clusters) is just a parameter change.
• Cache the auth token. Swift auth tokens expire (typically after a few hours). If the underlying client does not cache tokens, wrap the client in a service that stores the token in a cache pool and refreshes on 401 — otherwise every request pays the authentication round trip.
• Headers are your metadata store. Set Content-Type, cache-control, and custom X-Object-Meta-* headers at upload time; Swift has no other way to attach arbitrary metadata to an object.
• Integrate with the filesystem abstraction if you have one. If the project already uses Gaufrette or Flysystem, prefer a Swift adapter over this bundle — it gives you a stable interface and keeps the legacy wrapper isolated.

Gotchas and Tips

• It is abandoned. One release in 2015, one star, zero dependents. Symfony 2/3 service definitions, PHP 5.x style code, and no security updates. Treat it as a historical reference: read the source to understand Swift auth/object semantics, then seriously consider re-implementing against php-opencloud/openstack or the official OpenStack SDK before shipping to production.
• No test doubles shipped. The bundle offers no in-memory Swift implementation, so unit tests must mock the client interface yourself or run a local Swift/swift-init all container. Plan for an integration-test path early.
• Config key names are guess-bait. Without docs, misconfiguring tenant vs tenant_name, or a trailing slash on the auth URL, produces opaque auth failures. Read Configuration.php literally and mirror values that work with the raw client.
• Error handling: Swift throws typed exceptions for 404 (missing container/object) and 401 (expired token). Catch these explicitly — a blanket catch will mask an expired token as "file not found."
• Large file uploads may require Swift's segmented/large-object API (SLO/DLO) depending on the cluster's max object size. The 2015 client likely only supports single-part PUT; verify against your Swift deployment's max_file_size.
• Debugging: point the client at a local Swift devstack, and log the raw request/response if the wrapper exposes a logger. The most common production surprise is ACL/container policy — the container may be private when you assumed public, or vice versa.
• Extension points are limited: the main lever is replacing the client factory or decorating the client service in your own bundle. Don't try to monkey-patch the bundle's DIC; own the wrapper instead.