Coder Social home page Coder Social logo

php-session's Introduction

PHP Session library

Latest Stable Version License Total Downloads CI CodeCov PSR1 PSR4 PSR12

Translations: Español

PHP library for handling sessions.



Requirements

  • Operating System: Linux | Windows.

  • PHP versions: 8.0 | 8.1 | 8.2 | 8.3.

Installation

The preferred way to install this extension is through Composer.

To install PHP Session library, simply:

composer require josantonius/session

The previous command will only install the necessary files, if you prefer to download the entire source code you can use:

composer require josantonius/session --prefer-source

You can also clone the complete repository with Git:

git clone https://github.com/josantonius/php-session.git

Available Classes

Session Class

Josantonius\Session\Session

Starts the session:

/**
 * @throws HeadersSentException        if headers already sent.
 * @throws SessionStartedException     if session already started.
 * @throws WrongSessionOptionException if setting options failed.
 * 
 * @see https://php.net/session.configuration for List of available $options.
 */
public function start(array $options = []): bool;

Check if the session is started:

public function isStarted(): bool;

Sets an attribute by name:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function set(string $name, mixed $value): void;

Gets an attribute by name:

/**
 * Optionally defines a default value when the attribute does not exist.
 */
public function get(string $name, mixed $default = null): mixed;

Gets all attributes:

public function all(): array;

Check if an attribute exists in the session:

public function has(string $name): bool;

Sets several attributes at once:

/**
 * If attributes exist they are replaced, if they do not exist they are created.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public function replace(array $data): void;

Deletes an attribute by name and returns its value:

/**
 * Optionally defines a default value when the attribute does not exist.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public function pull(string $name, mixed $default = null): mixed;

Deletes an attribute by name:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function remove(string $name): void;

Free all session variables:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function clear(): void;

Gets the session ID:

public function getId(): string;

Sets the session ID:

/**
 * @throws SessionStartedException if session already started.
 */
public function setId(string $sessionId): void;

Update the current session ID with a newly generated one:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function regenerateId(bool $deleteOldSession = false): bool;

Gets the session name:

public function getName(): string;

Sets the session name:

/**
 * @throws SessionStartedException if session already started.
 */
public function setName(string $name): void;

Destroys the session:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function destroy(): bool;

Session Facade

Josantonius\Session\Facades\Session

Starts the session:

/**
 * @throws HeadersSentException        if headers already sent.
 * @throws SessionStartedException     if session already started.
 * @throws WrongSessionOptionException if setting options failed.
 * 
 * @see https://php.net/session.configuration for List of available $options.
 */
public static function start(array $options = []): bool;

Check if the session is started:

public static function isStarted(): bool;

Sets an attribute by name:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function set(string $name, mixed $value): void;

Gets an attribute by name:

/**
 * Optionally defines a default value when the attribute does not exist.
 */
public static function get(string $name, mixed $default = null): mixed;

Gets all attributes:

public static function all(): array;

Check if an attribute exists in the session:

public static function has(string $name): bool;

Sets several attributes at once:

/**
 * If attributes exist they are replaced, if they do not exist they are created.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public static function replace(array $data): void;

Deletes an attribute by name and returns its value:

/**
 * Optionally defines a default value when the attribute does not exist.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public static function pull(string $name, mixed $default = null): mixed;

Deletes an attribute by name:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function remove(string $name): void;

Free all session variables:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function clear(): void;

Gets the session ID:

public static function getId(): string;

Sets the session ID:

/**
 * @throws SessionStartedException if session already started.
 */
public static function setId(string $sessionId): void;

Update the current session ID with a newly generated one:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function regenerateId(bool $deleteOldSession = false): bool;

Gets the session name:

public static function getName(): string;

Sets the session name:

/**
 * @throws SessionStartedException if session already started.
 */
public static function setName(string $name): void;

Destroys the session:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function destroy(): bool;

Exceptions Used

use Josantonius\Session\Exceptions\HeadersSentException;
use Josantonius\Session\Exceptions\SessionException;
use Josantonius\Session\Exceptions\SessionNotStartedException;
use Josantonius\Session\Exceptions\SessionStartedException;
use Josantonius\Session\Exceptions\WrongSessionOptionException;

Usage

Example of use for this library:

Starts the session without setting options

use Josantonius\Session\Session;

$session = new Session();

$session->start();
use Josantonius\Session\Facades\Session;

Session::start();

Starts the session setting options

use Josantonius\Session\Session;

$session = new Session();

$session->start([
    // 'cache_expire' => 180,
    // 'cache_limiter' => 'nocache',
    // 'cookie_domain' => '',
    'cookie_httponly' => true,
    'cookie_lifetime' => 8000,
    // 'cookie_path' => '/',
    'cookie_samesite' => 'Strict',
    'cookie_secure'   => true,
    // 'gc_divisor' => 100,
    // 'gc_maxlifetime' => 1440,
    // 'gc_probability' => true,
    // 'lazy_write' => true,
    // 'name' => 'PHPSESSID',
    // 'read_and_close' => false,
    // 'referer_check' => '',
    // 'save_handler' => 'files',
    // 'save_path' => '',
    // 'serialize_handler' => 'php',
    // 'sid_bits_per_character' => 4,
    // 'sid_length' => 32,
    // 'trans_sid_hosts' => $_SERVER['HTTP_HOST'],
    // 'trans_sid_tags' => 'a=href,area=href,frame=src,form=',
    // 'use_cookies' => true,
    // 'use_only_cookies' => true,
    // 'use_strict_mode' => false,
    // 'use_trans_sid' => false,
]);
use Josantonius\Session\Facades\Session;

Session::start([
    'cookie_httponly' => true,
]);

Check if the session is started

use Josantonius\Session\Session;

$session = new Session();

$session->isStarted();
use Josantonius\Session\Facades\Session;

Session::isStarted();

Sets an attribute by name

use Josantonius\Session\Session;

$session = new Session();

$session->set('foo', 'bar');
use Josantonius\Session\Facades\Session;

Session::set('foo', 'bar');

Gets an attribute by name without setting a default value

use Josantonius\Session\Session;

$session = new Session();

$session->get('foo'); // null if attribute does not exist
use Josantonius\Session\Facades\Session;

Session::get('foo'); // null if attribute does not exist

Gets an attribute by name setting a default value

use Josantonius\Session\Session;

$session = new Session();

$session->get('foo', false); // false if attribute does not exist
use Josantonius\Session\Facades\Session;

Session::get('foo', false); // false if attribute does not exist

Gets all attributes

use Josantonius\Session\Session;

$session = new Session();

$session->all();
use Josantonius\Session\Facades\Session;

Session::all();

Check if an attribute exists in the session

use Josantonius\Session\Session;

$session = new Session();

$session->has('foo');
use Josantonius\Session\Facades\Session;

Session::has('foo');

Sets several attributes at once

use Josantonius\Session\Session;

$session = new Session();

$session->replace(['foo' => 'bar', 'bar' => 'foo']);
use Josantonius\Session\Facades\Session;

Session::replace(['foo' => 'bar', 'bar' => 'foo']);

Deletes an attribute and returns its value or the default value if not exist

use Josantonius\Session\Session;

$session = new Session();

$session->pull('foo'); // null if attribute does not exist
use Josantonius\Session\Facades\Session;

Session::pull('foo'); // null if attribute does not exist

Deletes an attribute and returns its value or the custom value if not exist

use Josantonius\Session\Session;

$session = new Session();

$session->pull('foo', false); // false if attribute does not exist
use Josantonius\Session\Facades\Session;

Session::pull('foo', false); // false if attribute does not exist

Deletes an attribute by name

use Josantonius\Session\Session;

$session = new Session();

$session->remove('foo');
use Josantonius\Session\Facades\Session;

Session::remove('foo');

Free all session variables

use Josantonius\Session\Session;

$session = new Session();

$session->clear();
use Josantonius\Session\Facades\Session;

Session::clear();

Gets the session ID

use Josantonius\Session\Session;

$session = new Session();

$session->getId();
use Josantonius\Session\Facades\Session;

Session::getId();

Sets the session ID

use Josantonius\Session\Session;

$session = new Session();

$session->setId('foo');
use Josantonius\Session\Facades\Session;

Session::setId('foo');

Update the current session ID with a newly generated one

use Josantonius\Session\Session;

$session = new Session();

$session->regenerateId();
use Josantonius\Session\Facades\Session;

Session::regenerateId();

Update the current session ID with a newly generated one deleting the old session

use Josantonius\Session\Session;

$session = new Session();

$session->regenerateId(true);
use Josantonius\Session\Facades\Session;

Session::regenerateId(true);

Gets the session name

use Josantonius\Session\Session;

$session = new Session();

$session->getName();
use Josantonius\Session\Facades\Session;

Session::getName();

Sets the session name

use Josantonius\Session\Session;

$session = new Session();

$session->setName('foo');
use Josantonius\Session\Facades\Session;

Session::setName('foo');

Destroys the session

use Josantonius\Session\Session;

$session = new Session();

$session->destroy();
use Josantonius\Session\Facades\Session;

Session::destroy();

Tests

To run tests you just need composer and to execute the following:

git clone https://github.com/josantonius/php-session.git
cd php-session
composer install

Run unit tests with PHPUnit:

composer phpunit

Run code standard tests with PHPCS:

composer phpcs

Run PHP Mess Detector tests to detect inconsistencies in code style:

composer phpmd

Run all previous tests:

composer tests

TODO

  • Add new feature
  • Improve tests
  • Improve documentation
  • Improve English translation in the README file
  • Refactor code for disabled code style rules (see phpmd.xml and phpcs.xml)
  • Show an example of renewing the session lifetime
  • Feature to enable/disable exceptions?
  • Feature to add prefixes in session attributes?

Changelog

Detailed changes for each release are documented in the release notes.

Contribution

Please make sure to read the Contributing Guide, before making a pull request, start a discussion or report a issue.

Thanks to all contributors! ❤️

Sponsor

If this project helps you to reduce your development time, you can sponsor me to support my open source work 😊

License

This repository is licensed under the MIT License.

Copyright © 2017-present, Josantonius

php-session's People

Contributors

alirezasalehizadeh avatar chrisrowley14 avatar josantonius avatar owenvoke avatar peter279k avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

php-session's Issues

Cannot use bool as default value

Hello,
At line 79 of the file src/Session.php, there is the set function with the $value parameter which is type-hinted as a string with a default of (bool) false. This causes an issue I guess
Thanks !

Method has in class

Hi, i have a question.

Can you create a method with name "has" ? This method check if the key is isset in session.

RE: Status of this project

Hi There,

I am looking to use this library in a web application that would be running for like the next ten years. Is this project still being maintained?

Thanks

Namespace wrong in the readme

Hi, when installed through composer and then tried to use like stated in the readme:

use josantonius\Session\Session;
$session = new Session();

It will not find the class, since the namespace is capitalized and should read:

use Josantonius\Session\Session;

Otherwise great work

How to renew the expiration time?

When instantiating the object, an expiration time is established: For example.
Session::init($lifeTime);
I can also instantiate without expiration date and the session expires until it is destroyed:
Session::destroy($key, $prefix);

Well, I have a system that validates some parameters to access the user control panel and that allows only one login per user, that is, if someone else accesses from another computer, all previous sessions are destroyed and only the most recent one remains active.

The problem is: I do not want the session to be destroyed after a certain time AFTER creating it, rather I want it to be destroyed after a period of inactivity, therefore, what I need is that, every time the user validation is done refresh or re-add the 3600 seconds back to that already active session.

How could I do it?
Thanks for the help.

P.S. I am using Middlewares

Wrong class installed via composer

Hi, i'm getting a wrong class when I try to install this lib in my project.
I am using php 7.4
I run composer require josantonius/session --prefer-source and I get this class:

image

which is "slightly" different from this:

image

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.