zf-commons / zfc-user
A generic user registration and authentication module for ZF2. Supports Zend\Db and Doctrine2.
Installs: 1 023 138
Dependents: 126
Suggesters: 9
Security: 1
Stars: 494
Watchers: 85
Forks: 342
Open Issues: 58
Requires
- php: ^5.5|^7.0
- zendframework/zend-authentication: ^2.5
- zendframework/zend-crypt: ^3.0
- zendframework/zend-db: ^2.8
- zendframework/zend-form: ^2.9
- zendframework/zend-http: ^2.5
- zendframework/zend-hydrator: ^2.0
- zendframework/zend-i18n: ^2.7
- zendframework/zend-inputfilter: ^2.7
- zendframework/zend-loader: ^2.5
- zendframework/zend-modulemanager: ^2.7
- zendframework/zend-mvc: ^3.0
- zendframework/zend-mvc-plugin-flashmessenger: ^1.0
- zendframework/zend-mvc-plugin-prg: ^1.0
- zendframework/zend-servicemanager: ^3.0
- zendframework/zend-session: ^2.7
- zendframework/zend-stdlib: ^3.0
- zendframework/zend-validator: ^2.8
- zendframework/zend-view: ^2.8
Requires (Dev)
- phpmd/phpmd: 1.4.*
- phpunit/phpunit: >=3.7,<4
- squizlabs/php_codesniffer: 1.4.*
- zendframework/zend-captcha: ^2.6
Suggests
- zendframework/zend-captcha: Zend\Captcha if you want to use the captcha component
README
Created by Evan Coury and the ZF-Commons team
Introduction
ZfcUser is a user registration and authentication module for Zend Framework 2. Out of the box, ZfcUser works with Zend\Db, however alternative storage adapter modules are available (see below). ZfcUser provides the foundations for adding user authentication and registration to your ZF2 site. It is designed to be very simple and easy to extend.
More information and examples are available on the ZfcUser Wiki
Versions
Please use below table to figure out what version of ZfcUser you should use.
Storage Adapter Modules
By default, ZfcUser ships with support for using Zend\Db for persisting users. However, by installing an optional alternative storage adapter module, you can take advantage of other methods of persisting users:
- ZfcUserDoctrineORM - Doctrine2 ORM
- ZfcUserDoctrineMongoODM - Doctrine2 MongoDB ODM
Requirements
- Zend Framework 2 (latest master)
- ZfcBase (latest master).
Features / Goals
- Authenticate via username, email, or both (can opt out of the concept of username and use strictly email) [COMPLETE]
- User registration [COMPLETE]
- Forms protected against CSRF [COMPLETE]
- Out-of-the-box support for Doctrine2 and Zend\Db [COMPLETE]
- Robust event system to allow for extending [COMPLETE]
- Provide ActionController plugin and view helper [COMPLETE]
Installation
Main Setup
By cloning project
- Install the ZfcBase ZF2 module
by cloning it into
./vendor/
. - Clone this project into your
./vendor/
directory.
With composer
-
Add this project and ZfcBase in your composer.json:
"require": { "zf-commons/zfc-user": "^3.0" }
-
Now tell composer to download ZfcUser by running the command:
$ php composer.phar update
Post installation
-
Enabling it in your
application.config.php
file.<?php return array( 'modules' => array( // ... 'ZfcUser', ), // ... );
-
Then Import the SQL schema located in
./vendor/zf-commons/zfc-user/data/schema.sql
(if you installed using the Composer) or in./vendor/ZfcUser/data/schema.sql
.
Post-Install: Doctrine2 ORM
Coming soon...
Post-Install: Doctrine2 MongoDB ODM
Coming soon...
Post-Install: Zend\Db
- If you do not already have a valid Zend\Db\Adapter\Adapter in your service
manager configuration, put the following in
./config/autoload/database.local.php
:
<?php return array( 'db' => array( 'driver' => 'PdoMysql', 'hostname' => 'changeme', 'database' => 'changeme', 'username' => 'changeme', 'password' => 'changeme', ), 'service_manager' => array( 'factories' => array( 'Zend\Db\Adapter\Adapter' => 'Zend\Db\Adapter\AdapterServiceFactory', ), ), );
Navigate to http://yourproject/user and you should land on a login page.
Password Security
DO NOT CHANGE THE PASSWORD HASH SETTINGS FROM THEIR DEFAULTS unless A) you have done sufficient research and fully understand exactly what you are changing, AND B) you have a very specific reason to deviate from the default settings.
If you are planning on changing the default password hash settings, please read the following:
The password hash settings may be changed at any time without invalidating existing user accounts. Existing user passwords will be re-hashed automatically on their next successful login.
WARNING: Changing the default password hash settings can cause serious problems such as making your hashed passwords more vulnerable to brute force attacks or making hashing so expensive that login and registration is unacceptably slow for users and produces a large burden on your server(s). The default settings provided are a very reasonable balance between the two, suitable for computing power in 2013.
Options
The ZfcUser module has some options to allow you to quickly customize the basic
functionality. After installing ZfcUser, copy
./vendor/zf-commons/zfc-user/config/zfcuser.global.php.dist
to
./config/autoload/zfcuser.global.php
and change the values as desired.
The following options are available:
- user_entity_class - Name of Entity class to use. Useful for using your own
entity class instead of the default one provided. Default is
ZfcUser\Entity\User
. - enable_username - Boolean value, enables username field on the
registration form. Default is
false
. - auth_identity_fields - Array value, specifies which fields a user can use as the 'identity' field when logging in. Acceptable values: username, email.
- enable_display_name - Boolean value, enables a display name field on the
registration form. Default value is
false
. - enable_registration - Boolean value, Determines if a user should be
allowed to register. Default value is
true
. - login_after_registration - Boolean value, automatically logs the user in
after they successfully register. Default value is
false
. - use_registration_form_captcha - Boolean value, determines if a captcha should
be utilized on the user registration form. Default value is
true
. (Note, right now this only utilizes a weak Zend\Text\Figlet CAPTCHA, but I have plans to make all Zend\Captcha adapters work.) - login_form_timeout - Integer value, specify the timeout for the CSRF security field of the login form in seconds. Default value is 300 seconds.
- user_form_timeout - Integer value, specify the timeout for the CSRF security field of the registration form in seconds. Default value is 300 seconds.
- use_redirect_parameter_if_present - Boolean value, if a redirect GET parameter is specified, the user will be redirected to the specified URL if authentication is successful (if present, a GET parameter will override the login_redirect_route specified below).
- login_redirect_route String value, name of a route in the application which the user will be redirected to after a successful login.
- logout_redirect_route String value, name of a route in the application which the user will be redirected to after logging out.
- password_cost - This should be an integer between 4 and 31. The number
represents the base-2 logarithm of the iteration count used for hashing.
Default is
10
(about 10 hashes per second on an i5). - enable_user_state - Boolean value, enable user state usage. Should user's state be used in the registration/login process?
- default_user_state - Integer value, default user state upon registration. What state user should have upon registration?
- allowed_login_states - Array value, states which are allowing user to login. When user tries to login, is his/her state one of the following? Include null if you want user's with no state to login as well.
Changing Registration Captcha Element
NOTICE These instructions are currently out of date.
By default, the user registration uses the Figlet captcha engine. This is because it's the only one that doesn't require API keys. It's possible to change out the captcha engine with DI. For example, to change to Recaptcha, you would add this to one of your configuration files (global.config.php, module.config.php, or a dedicated recaptcha.config.php):
<?php
// ./config/autoload/recaptcha.config.php
return array(
'di'=> array(
'instance'=>array(
'alias'=>array(
// OTHER ELEMENTS....
'recaptcha_element' => 'Zend\Form\Element\Captcha',
),
'recaptcha_element' => array(
'parameters' => array(
'spec' => 'captcha',
'options'=>array(
'label' => '',
'required' => true,
'order' => 500,
'captcha' => array(
'captcha' => 'ReCaptcha',
'privkey' => RECAPTCHA_PRIVATE_KEY,
'pubkey' => RECAPTCHA_PUBLIC_KEY,
),
),
),
),
'ZfcUser\Form\Register' => array(
'parameters' => array(
'captcha_element'=>'recaptcha_element',
),
),
),
),
);