This package is an ultralight PHP wrapper for the Google App Engine Image server.
It can access images in stored in a dedicated GCS bucket and return you an image-serving URL. With the URL you can generate different sizes and variants on the fly - all powered by the underlying Google service.
Please see Usage section for examples.
Important notice
Before you continue please make sure you have a Google Project in your Google Cloud Console. It may be necessary to enable billing by submitting a credit card to your account.
- Clone this repo
git clone https://github.com/makeabledk/appengine-php-imageserver.git- Open
index.php - Fill in your Google Project ID around line 19
$app['bucket_name'] = 'YOUR-PROJECT_ID.appspot.com'; // ie. project-xyz.appspot.comYou can find your project-id under the panel Project info on the GCS project dashboard.
Follow instructions from https://cloud.google.com/sdk/
You are now ready to deploy the image server to our Google App Engine.
The following code will deploy an App Engine instance and create two Google Storage buckets.
composer install
gcloud config set project YOUR-PROJECT-ID # ie. project-xyz
gcloud app deploy
gcloud app browse
The last command will open the project in your browser - something like: https://project-xyz.appspot.com/
- Navigate to the Storage section in your Google Console. Upload any image file and copy the filename.
- Apply the image filename (or path) to the app-engine URL like: https://YOUR-PROJECT_ID.appspot.com/?image=image.jpg
- The app-engine service should now return your imageserving URL which you can store and use to manipulate the image on-the-fly
Now that you have an image serving URL you can generate different versions just by changing some parameters:
Max dimension 200px:
Cropped to 400x150px:
Cropped, circled, rotated 90deg and converted to PNG
Unfortunately it seems Google has no official documentation for the available parameters. Nevertheless we came across this handy Stacoverflow question that mentions quite a few parameteres.
They are listed here:
SIZE / CROP
- s640 — generates image 640 pixels on largest dimension
- s0 — original size image
- w100 — generates image 100 pixels wide
- h100 — generates image 100 pixels tall
- s (without a value) — stretches image to fit dimensions
- c — crops image to provided dimensions
- n — same as c, but crops from the center
- p — smart square crop, attempts cropping to faces
- pp — alternate smart square crop, does not cut off faces (?)
- cc — generates a circularly cropped image
- ci — square crop to smallest of: width, height, or specified =s parameter
- nu — no-upscaling. Disables resizing an image to larger than its original resolution.
PAN AND ZOOM
- x, y, z: — pan and zoom a tiled image. These have no effect on an untiled image or without an authorization parameter of some form (see googleartproject.com).
ROTATION
- fv — flip vertically
- fh — flip horizontally
- r{90, 180, 270} — rotates image 90, 180, or 270 degrees clockwise
IMAGE FORMAT
- rj — forces the resulting image to be JPG
- rp — forces the resulting image to be PNG
- rw — forces the resulting image to be WebP
- rg — forces the resulting image to be GIF
- v{0,1,2,3} — sets image to a different format option (works with JPG and WebP) Forcing PNG, WebP and GIF outputs can work in combination with circular crops for a transparent background. Forcing JPG can be combined with border color to fill in backgrounds in transparent images.
ANIMATED GIFs
- rh — generates an MP4 from the input image
- k — kill animation (generates static image)
MISC.
- b10 — add a 10px border to image
- c0xAARRGGBB — set border color, eg. =c0xffff0000 for red
- d — adds header to cause browser download
- e7 — set cache-control max-age header on response to 7 days
- l100 — sets JPEG quality to 100% (1-100)
- h — responds with an HTML page containing the image
- g — responds with XML used by Google's pan/zoom
FILTERS
- fSoften=1,100,0: - where 100 can go from 0 to 100 to blur the image
- fVignette=1,100,1.4,0,000000 where 100 controls the size of the gradient and 000000 is RRGGBB of the color of the border shadow
- fInvert=0,1 inverts the image regardless of the value provided
- fbw=0,1 makes the image black and white regardless of the value provided
Checkout our Laravel package: makeabledk/laravel-cloud-images
The official documentation at the time of writing states that you only pay for the actual storage of the images + the usage of App Engine to process the images. There is no additional fee for the Images API.
https://cloud.google.com/appengine/docs/standard/java/images/#quotas-limits-pricing
It's worth noting that the official documentation for App Engine Images is extremely scarce. For this reason you should do your own research and be the judge of how comfortable you are relying on this API for your production systems.
At Makeable we have used this service to process and host more than 1 million images since 2016 with no issues whatsoever.
- Google Documentation: Images API for Java - This is the most thourough mentioning of available parameters
- Google Documentation: Images API for PHP
- App Engine PHP SDK on Github - This is the underlying proxy library that's used in this project
We are happy to receive pull requests for additional functionality. Please see CONTRIBUTING for details.
Attribution-ShareAlike 4.0 International. Please see License File for more information.
