Installation

Sergey Chernyshev edited this page Feb 17, 2018 · 8 revisions

One of the important goals for the project are simple installation and upgrades. Let us know where you experience problems and we'll try to reduce the friction.

When you unpack the code into users folder, open it in your browser and installation wizard will walk you through the process.


Prerequisites

Startup API uses PHP 5.3.0 or newer, after all it was released on 6/30/2009.

It also requires a few common extensions that might not be installed on your LAMP server. Click the links for installation instructions:

  • php-mysqli for support of more performant and secure MySQL interface
  • php-mcrypt encryption library for better security
  • libcurl / cURL for various network operations
  • php-mbstring for international strings support (user names, for example)

Get the code

From Git repository

Get the code from GitHub and place into the root directory of your website.

The following command places Startup API in the users folder (recommended default):

git clone git://github.com/StartupAPI/users.git users

If you already use Git for your code, you can use StartupAPI as a submodule:

git submodule add git://github.com/StartupAPI/users.git users

NOTE: A submodule can only be added from your git repository root directory. If your WEBROOT is not the root directory you can specify the applicable directory, e.g. www/users

Downloadable packages

If you do not use Git, you can just download latest package from package archive section.

Create MySQL database

If you don't have it yet, create MySQL database and get user credentials for it with following permissions: CREATE, ALTER, CREATE TEMPORARY TABLES, DELETE, DROP, INDEX, INSERT, SELECT, UPDATE.

mysql> CREATE SCHEMA IF NOT EXISTS example_schema;
mysql> CREATE USER schema_user@localhost IDENTIFIED BY 'password';
mysql> GRANT INSERT,UPDATE,DELETE,SELECT,CREATE,ALTER,DROP,CREATE TEMPORARY TABLES ON example_schema.* TO schema_user@localhost;

Some of these permissions (CREATE, ALTER, DROP, INDEX) are needed for creating database schema and can be removed after the installation step has been completed.

CREATE TEMPORARY TABLES is required for aggregatepoints.php script.

There is an issue #79 open for separating admin credentials (for schema manipulation) from application credentials. Why it is important to do so, see here: Why GRANT ALL is bad by Ronald Bradford.

Create configuration file

Copy the sample configuration file from the installed users folder to the base directory of your website.

cp users/users_config.sample.php users_config.php

Open the users_config.php file with your favorite editor, and as minimum, seed the secret for cookie encryption and set your defined MySQL database credentials

<?php
/**
 * You must fill it in with some random string
 * this protects some of your user's data when sent over the network
 * and must be different from other sites
 */
UserConfig::$SESSION_SECRET= '...type.some.random.characters.here...';
    
/**
 * Database connectivity
 */
UserConfig::$mysql_db = '...database...';
UserConfig::$mysql_user = '...username...';
UserConfig::$mysql_password = '...password...';
#UserConfig::$mysql_host = 'localhost';
#UserConfig::$mysql_port = 3306;
#UserConfig::$mysql_socket = '/tmp/mysql.sock'; // in case you are using socket to connect

Build code and schema

Run make to generate database tables and other submodules and files required by the different parts of Startup API.

cd users
make

When completed you will see the following

...
[*** SUCCESS ***] Installation and upgrade of Startup API completed successfully

Without make

If you do not have make installed on your system, you can get the latest downloadable package (which contains all files including submodules) instead of checking code out of the repository.

For schema setup, just run

cd users
php dbupgrade.php

open http://yoursite/users/dbupgrade.php in your browser - this will create database schema (or update it if you already have older version).

Configure authentication modules

Uncomment and configure API keys for more authentication modules for Facebook, Twitter, Google and etc.

Complete Installation

You should now in a browser goto http://yourwebsite.com/users and complete the installation via the provided Wizard.


Use it

Start building your app by copying code from sample.php.

Global code

Basically, you'll need to include users.php at the top of the file

<?php
require_once( __DIR__ . '/users/users.php');

StartupAPI uses Twig templating library internally and you're encouraged to use it for your application as well as it lets you separate logic from presentation and supports field escaping by default which is important for security.

Startup API already bundles Twig and initializes it upon load so all you need is to register your own templates with it.

<?php
require_once( __DIR__ . '/users/users.php');
StartupAPI::$template->getLoader()->addPath(__DIR__ . '/templates/', 'myapp');

Twig uses a global template data object, you should start by getting values already initialized by StartupAPI and then build on it for your own pages. You can also reuse values already initialized which can save you some work.

// start with global template data needed for Startup API menus and stuff
$template_info = StartupAPI::getTemplateInfo();

After you added your own fields to the $template_info object, you can just call Twig's display() method to render full template.

// render tempalte as HTML
StartupAPI::$template->display('@myapp/homepage.html.twig', $template_info);

This will render a Twig template located in /templates/homepage.html.twig file in your project.

In order to use Statup API's menu system, including power strip with login/logout buttons, account management and etc. you can just extend base page template and fill content block with your page's content.

{% extends '@startupapi/page.html.twig' %}
{% block content %}
<section>
   <h1>My page</h1>
   <p>This is the content of my project</p>
</section>
{% endblock %}

See page.html.twig template for other blocks to override and Twig's template documentation for syntax.

Styling and themes

Startup API uses Bootstrap v3 CSS framework for styling (in default awesome template theme) and can be a good starting point for your application.

You can also configure different CSS themes provided by Bootswatch project. In users_config.php file, set UserConfig::$bootstrapTheme to one of the theme names to choose a different theme.

/**
 * If specified, StartupAPI::head() will include this Twitter Bootstrap Theme instead of default one
 */
UserConfig::$bootstrapTheme = 'flatly';

Enabling dev mode in users_config.php (don't use it in production) will add theme drop-down to the power strip so you can pick and choose themes on a current page and to help you make your HTML code compatible in case you'll want to switch a theme later.

UserConfig::$DEVMODE = TRUE;

See theme example project that only has theme-specific configuration and showcases Bootswatch themes.

Get a User

and then use either StartupAPI::getUser() static method to get a user object

/**
 * Get User object or null if user is not logged in
 */
$current_user = StartupAPI::getUser();

or if you want to protect the page from anonymous users, use StartupAPI::requireLogin() instead - this will automatically redirect to a login form and back to yout page after user successfully logged in or registered.

/**
 * Get User object or redirect to login page if user is not logged in
 */
$current_user = StartupAPI::requireLogin();

you can get numeric user ID to use in your data model by calling getID() method

/**
 * Get user's unique ID
 */
$user_id = $current_user->getID();

Use Accounts

It is recommended to use Accounts instead of Users to associate your data. This way you'll be able to upgrade your initial single-user setup to multi-user accounts and work with subscription payments in the future without changing any of your code, just Startup API configuration. Each user gets one free account associated with them by default so it is the same as using users out of the box.

Similarly to Users, Accounts have unique integer IDs associated with them so you can display data associated with user's current account:

/**
 * Get current Account object
 */
$current_account = $current_user->getCurrentAccount();
$current_account_id = $current_account->getID();

or you can get a list of all user accounts:

<?php
/**
 * Get all user accounts
 */
$user_accounts = $current_user->getAccounts();

Now what?

Sit back and relax Go implement your business logic now. You can call getID(), getName() and other methods on the user and account objects to utilize it in your code.

Upgrading

As usual, make a backup of the database to avoid loosing data in case of disasters.

Then just run make - it should grab the latest code and run database update scripts to bring schema up to date with the code.

make
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.