Download the PHP package floorplanner/roomstyler-api-php without Composer

Roomstyler PHP API

This is a PHP library that makes it easier to use the Roomstyler RESTful API. It is intended to be a wrapper for the API so that you, as user of the API will never have to write your own HTTP requests but instead can simply call a method to do it for you.

Table of contents

• Table of contents
• Installation
  • Manual (using GUI)
  • Manual (using git + command line)
  • Composer
• Getting started
  • Anonymous API access
  • User API access
  • Whitelabel API access
  • Full API access
  • Settings
• Structure
  • RoomstylerApi
  • RoomstylerMethodBase
  • RoomstylerModelBase
• Errors
  • RoomstylerError
  • any()
  • get()
  • each()
• API endpoints
  • Rooms
  • List
  • List whitelabel
  • Find
  • Search
  • Panorama's
  • Panorama
  • Comment
  • Toggle love
  • Change owner
  • Delete
  • Products
  • Loves
  • Related rooms
  • Comments
  • Add tags
  • Remove tags
  • Render
  • Users
  • Find
  • Create
  • Login
  • Delete
  • Loved rooms
  • Collections
  • Specific user collections
  • Contests
  • List
  • Find
  • Entries
  • Contest Entries
  • Vote
  • Materials
  • Find
  • Components
  • Find
  • Categories
  • List
• 3dplanner
  • Embed

Installation

Based on the roomstyler RESTful API, should anything be/remain unclear after reading the docs, check the documentation on there as well to see if it is more clear. Also, this is not a 1-on-1 copy of the API, some method calls are grouped (render for instance can do panorama, hq and 2d aside from the default 3d) or have a slightly more convenient way of adding parameters.

Manual (using GUI)

1. Go to github.com/floorplanner/roomstyler-api-php
2. Click on the Clone or download button
3. Select Download ZIP
4. Extract the .zip and move or copy it to the root of the project
5. Require roomstyler-api-php-master/api/RoomstylerApi.php in your application

Manual (using git and command line)

This command clones the repository to project-root/roomstyler-api-php/, to require it add:

Composer (using command line)

Getting Started

Anonymous API access

When you want to read public data

User API access

For personal use, read global data or perform actions on rooms as the signed in user (whitelabel users can also login)

Whitelabel API access

For when you want to read global data and read, write or modify your own whitelabel data

Godmode API access

For the those who want to maximize their integration potential, this allows you to read and write and modify data of your whitelabel and your own rooms and perform actions on rooms as the signed in user

After doing this setup you should probably run a simple test to check if you can actually get a response back from a call.

More configuration options

We just talked about the user and whitelabel options that can be passed to the constructor of the RoomstylerApi class but there are more options:

• protocol
  • default: https
    Specify the default protocol
• whitelabel
  • default: []
    Logs in a whitelabel (discussed above)
• user
  • default: []
    Logs in a user (discussed above)
• host
  • default: roomstyler.com
    The default hostname for the API
• prefix
  • default: api
    The default namespace that prepends every request route e.g. rooms/10 => api/rooms/10
• token
  • default: NULL
    When you log in through the user option this property will be set to the server generated token
• timeout
  • default: 5
    Maximum number of seconds to allow cURL to execute a function
• language
  • default: en
    Specify the editor language, supports: en, fr, de, es, nl
• connect_timeout
  • default: 30
    Maximum number of seconds to wait before connection times out (use 0 to wait indefinitely)
• request_headers
  • default: ['Content-Type: application/json; charset=utf-8']
    The default content type used to communicate with our API using POST requests
• debug
  • default: false
    Set to true to wrap results in an array containing result and request_info which can be used to view the request

Everything is already setup to work with the API so you barely have to change these settings. The option you'll most likely be using is debug which allows you to take a peek into the request.

Structure

This is a general overview of the structure of the core objects behind the API, I will try to explain what you can do and when you can do it as best as I can. The API is OOP only, which means you're going to have to apply a little bit of PHP's OOP but don't worry, it'll be easy!

RoomstylerApi

Starting with the RoomstylerApi class, this is the base for the entire API. It contains the settings and defaults that we've already discussed here

It also handles calls like this that you will be using:

If you're someone who has done OOP for some time and are familiar with PHP's magic methods and more specifically the __get magic method you'll know exactly what I'm talking about.

When you call something like ->components on the $api (Could be any variable name, must be an instance of the RoomstylerApi class) the $api will look up a class with the name of RoomstylerComponentMethods.

It does this by first converting whatever property you're trying to call to its singular form so components becomes component, then converting the first character to uppercase so component becomes Component and last but not least it prepends Roomstyler and appends Methods so that the final result becomes RoomstylerComponentMethods.

If you're already using the singular form of a word, e.g. component then the step to convert will do nothing and it will still uppercase the first character and prepend Roomstyler and append Methods

This RoomstylerComponentMethods class extends RoomstylerMethodBase and allows you to call the documented component aggregation methods.

Essentially this means that you can call any property and get either an instance of a class back if it exists and is included, or a Fatal Error: Class 'Roomstyler[NonExistentClass]Methods' not found in....

RoomstylerMethodBase

This is the base class behind the scenes that allows you to use any and all of the RoomstylerApi->_settings within an instance of Roomstyler[...]Methods It's purpose is to provide a standard interface for actions you execute to get a dataset.

RoomstylerModelBase

This is the base class behind the returned results from the requests. You use the methods in Roomstyler[...]Methods to get a set of results (through some find(), index() or search() action) after which you get a single object or an array of objects back which you can then manipulate.

Properties

This base class is actually more useful than the RoomstylerMethodBase since this one does the same and more, it also dynamically populates itself with properties returned from the API.

To get an idea of what I'm talking about, consider this json response from api/users/972691 it should look something like this:

And compare it to the return object that would look like this after a successful request and being __constructed

Now all the properties that start with an underscore (_) are also either :private or :protected which means we can't access them. If you try accessing this freshly fetched users _whitelabel property $user->_whitelabel it would simply return Notice: Undefined property: RoomstylerUser::$_whitelabel

If you tried to access the public (and dynamically populated) id on the other hand, you would get either NULL or it's value if it's set. The same goes for all other properties. Normally you would get a notice if you call a property that does not exist on an object ($user->non_existent_prop): Notice: Undefined property: RoomstylerUser::$non_existent_prop but since the fields are subject to change this would mean that you could get random Notice errors for no reason.

Because of this, all properties that do not exist or aren't public (except errors which is made public through __get) will return NULL.

Methods

The RoomstylerModelBase class also provides us with some other methods we can use to see wether the object actually exists() (not just an empty object - but actually having properties), or if the object in question has any errors

This is done (using our $user initiated on top) by calling $user->errors which will return a RoomstylerError object or $user->exists() to check if any property is set at all.

Errors

Every object returned from the API will have an accessible errors property that has a few methods. To check wether any of the objects contains any error (including http errors)

the maximum limit of the index call is 50. if this is exceeded the server will return a JSON error and an Unprocessable Entity (422) http error

To access these errors, call the errors property on a single entity. It will return an instance of the RoomstylerError class.

RoomstylerError

The RoomstylerError class has three methods, one to get() all the errors. One to see if there are each() error.

They will be explained using this example request.

(This request will error out since the max. limit for the index() function is 50)

Check if there are errors

The any() function will return true if any errors including any http errors occured.

Get all errors

The get() function will return an array of errors including http errors. If there are no errors, an empty array is returned.

The array returned is associative and will contain numeric and string keys. As you might be able to see below, the errors have different depths making it hard to property loop the errors. The solution for this is the builtin each() method which is explained later.

Loop all the errors

If there are errors, you can loop these through the each() function. It takes one parameter, which is a closure or callable function that itself takes one (optionally two) parameter(s) The first parameter contains the error message of an error and the second parameter will contain it's parent keys if it was a nested hash.

As we know the above $response example gives us two errors, one through a nested json object with an error key which contains the error. And a http error since we're requesting too much data.

If we'd print the get() function with this example, the errors array would look like this:

Knowing the structure of the errors, if we build something like this:

The output will look like this:

If the error key wasn't an error but instead another hash with say a quantity key containing the same error, the output for the same request would look like:

API endpoints

Rooms

Aggregation

Getting search meta data

PHP snippet

Method signature

Parameters

• None

Fetching rooms

PHP snippet

Method signature

Parameters

• $params - Optional (Defaults do get set) - An array containing any the following keys:
  • limit - Optional (Default 50) - A number between (and including) 1 and 50
  • page - Optional (Default 1) - A number that defines the page you're on (useful for pagination)
  • category - Optional (see RoomstylerSearchMeta) - Filters results within specified category
  • last_updated - Optional - List rooms updated after a given timestamp
  • created - Optional - List rooms created after a given timestamp
  • skip_last_updated - Optional (Recommended, Default true) - skips fetching last updated room, significantly speeds up requests
  • skip_total - Optional (Recommended, Default true) - skips fetching a count of all rooms, significantly speeds up requests
  • order - Optional - Order results based on a room attribute (see a RoomstylerRoom object for a list of properties)
  • direction - Required if order specified - either asc or desc
  • user_id - Optional - fetch rooms owned by this user (requires user access)
  • whitelabel - Optional - fetch rooms owned by your whitelabel (requires whitelabel access)
  • tag - Optional - Filter rooms by given tag

Fetching whitelabel rooms

This method accepts the same parameters as the non-scoped index method! The only difference is that the optional whitelabel parameter is set to the whitelabel user for you

PHP snippet

Method signature and parameters: see Fetching Rooms

Finding a specific room

PHP snippet

Method signature

Parameters

• $id - The id of the room to fetch

Searching rooms

PHP snippet

Method signature

Parameters

• $params - Optional (Defaults do get set) - An array containing any the following keys:
  • q - Required - A search string
  • limit - Optional (Default 50) - A number between (and including) 1 and 50
  • page - Optional (Default 1) - A number that defines the page you're on (useful for pagination)
  • since - Optional (see RoomstylerSearchMeta) - Filters results within specified timeframe
  • category - Optional (see RoomstylerSearchMeta) - Filters results within specified category
  • style - Optional (see RoomstylerSearchMeta) - Filters results within specified style
  • kind - Optional - If it has the value of own it will search through the logged in users rooms (requires user access)

Fetching panoramas

PHP snippet

Method signature

Parameters

• $params - Optional (Defaults do get set) - An array containing any the following keys:
  • limit - Optional (Default 50) - A number between (and including) 1 and 50
  • page - Optional (Default 1) - A number that defines the page you're on (useful for pagination)
  • since - Optional (see RoomstylerSearchMeta) - Filters results within specified timeframe
  • skip_total - Optional - skips counting of panorama's, speeds up request slightly if true

Actions

Lets say Let's initialize a $room variable and use that in the following requests like so:

Fetching a room panorama

PHP snippet

Method signature

Parameters

• $params - Optional (Defaults do get set) - An array containing any the following keys:
  • krpano_url - When supplied, adds a krpano_url property containing a template url to use for rendering a cube image in krpano.

Comment on a room

PHP snippet

Method signature

Parameters

• $content - The comment text to be placed on the room

Toggle love on a room

PHP snippet

Method signature

Parameters

• None

Change owner of a room

PHP snippet

Method signature

Parameters

• $user_id - The target user that will be the new owner of the subject room (should be a user(id) of your whitelabel)

Delete a room

PHP snippet

Method signature

Parameters

• None

Fetch products used in the room

PHP snippet

Method signature

Parameters

• None

Fetch users loves of the room

PHP snippet

Method signature

Parameters

• None

Fetch related rooms of a room

PHP snippet

Method signature

Parameters

• None

Fetch comments on a room

PHP snippet

Method signature

Parameters

• None

Add tags to a room

PHP snippet

OR

Method signature

Parameters

• $tags - Required - An array of individual tags or a string of comma-seperated tags

Remove tags from a room

PHP snippet

OR

Method signature

Parameters

• $tags - Required - An array of individual tags or a string of comma-seperated tags

Render room in 2D, 3D, HD 3D or panorama

PHP snippet

Method signature

Parameters

• $mode - Optional (Either 2d, panorama or hq, any other strings will be ignored) - Specify rendering method, if left empty it will render in 3D, otherwise it will render either 2d, panorama or hq
• $params - An array containing any the following keys:
  • width - Optional (Default value of 960 for normal and 2d renders, 1920 for hq and ignored for panorama) - Width at which to render room
  • height - Optional (Default value of 540 for normal and 2d renders, 1920 for hq and ignored for panorama) - Height at which to render room
  • size - Optional (Default value of 1080 for panorama, ignored for the rest) - Size at which to render cube images for panorama
  • callback - Optional (Required if $mode is set to 2d.) - A callback url that will receive a POST request when rendering is done

Users

Aggregation, Creation and Login

Finding users

PHP snippet

OR

OR

Method signature

Parameters

• $ids - Required - The id of a user, an array of ids or a string of comma seperated ids

Create a user

PHP snippet

Method signature

Parameters

• $params - Required
  • email - Required - Email we want to use for this account
  • username - Required
  • password - Required

Login

If you read over the user access setup section I showed an example of logging in as a user within the constructor of the object. It is however, also possible to login seperately like this, if You didn't login before and call this function manually later, all requests from then on will have user access.

This function also returns the token needed to use in other requests such as to comment or love a room.

Also, if you're already logged in you do not need to use this function.

PHP snippet

Method signature

Parameters

• $email - Required - Email to use
• $password - Required - Password for the account

Actions

Let's initialize a $user variable and use that in the following requests like so:

Delete a user

Deletes a given user

PHP snippet

Method signature

Parameters

• None

Get user loved rooms

PHP snippet

Method signature

Parameters

• $params - Optional (Defaults do get set) - An array containing any the following keys:
  • page - Optional - The page on which you're on (sets query offset to (page - 1) * per_page)
  • per_page - Optional - The amount of results to display on a page
  • skip_total - Optional (Default true) - skips counting results, speeds up query slightly

Get user collections

PHP snippet

Method signature

Parameters

• None

Get specific user collection

PHP snippet

Method signature

Parameters

• $id - Required - which of the users' collections to fetch

Contests

Aggregation

Fetch contests

PHP snippet

Method signature

Parameters

• $params - Optional (Defaults do get set) - An array containing any the following keys:
  • per_page - Optional (Default 25) - A number between (and including) 1 and 50
  • page - Optional (Default 1) - A number that defines the page you're on (useful for pagination)
  • status - Optional - Either "finished", "open" or "vote"
  • title - Optional - Return only contests where given string is contained within their title

Fetch a contest

PHP snippet

Method signature

Parameters

• $id - Required - the id of the contest to fetch

Actions

Let's initialize a $contest variable and use that in the following requests like so:

Fetch contest entries

PHP snippet

Method signature

Parameters

• $params - Optional (Defaults do get set) - An array containing any the following keys:
  • per_page - Optional (Default 25) - A number between (and including) 1 and 50
  • page - Optional (Default 1) - A number that defines the page you're on (useful for pagination)
  • order - Optional - Attribute to order by and the direction to order by
  • rand_seed - Optional - If supplied, entries will be returned psuedo-random based on the seed (must be an integer)

Contest entries

Actions

Let's initialize a $contest_entry variable and use that in the following requests like so:

Vote for a contest entry

PHP snippet

Method signature

Parameters

• None

Material

Aggregation

Find a material item

PHP snippet

Method signature

Parameters

• $id - Required - the id of the material item to fetch

Component

Aggregation

Find a component item

PHP snippet

Method signature

Parameters

• $id - Required - the id of the component item to fetch

Categories

Aggregation

Fetching categories

PHP snippet

Method signature

Parameters

• None

3dplanner

Embedding the 3dplanner

PHP snippet

Method signature

Parameters

• $opts - Optional (Defaults do get set) - An array containing any the following keys:
  • room_url - Optional - Opens a room_url (returned from the RoomstylerRoom->url property)
  • token - Optional - Log in a user through a token
  • language - Optional - Set the language for the editor to use, en, es, nl, fr and de
  • login - Optional - if false, prevents all logins
• $html_opts - Optional (Defaults do get set) - An array consisting of valid html attribute => value pairs
  • frameborder - Optional (Default 0) - HTML prop to hide the border around the editor
  • width - Optional (Default 1024) - Width of the editor iframe
  • height - Optional (Default 768) - Height of the editor iframe