fundevogel/php-thx

Acknowledge the people behind your dependencies - give back & spread love!


Keywords
love, gratitude, appreciation, gratefulness, thankfulness
License
GPL-3.0

Documentation

php-thx

Release License Issues Status

A very simple PHP library for acknowledging the people behind your frontend dependencies - and giving thanks.

Getting started

Install this package with Composer:

composer require S1SYPHOS/php-thx

Note: For yarn v2 support, the php-yaml package is required!

Usage

First, determine the paths to your files (datafile & lockfile, see below):

<?php

require_once('vendor/autoload.php');

use S1SYPHOS\Thx;

$pkgFile = 'path/to/composer.json';                # or 'package.json' for NPM / Yarn
$lockFile = 'path/to/composer.lock'                # or 'package-lock.json' for NPM / 'yarn.lock' for Yarn
$cacheDriver = 'file';                             # Optional: Cache driver, see below
$cacheSettings = ['storage' => '/path/to/cache'];  # Optional: Cache settings, see below

Note: For available cache drivers & settings, see here!

Passing these options to new Thx() creates an instance:

$obj = new Thx($pkgFile, $lockFile, $cacheDriver, $cacheSettings);

.. which you may configure to your liking by using:

  • setTimeout(int $seconds)
  • setCacheDuration(int $days)
  • setUserAgent(string $userAgent)
  • setBlockList(array $blockList)
# For example:

$obj->setCacheDuration(7);                    # Cache results for one week
$obj->setBlockList(['php', 'some/library']);  # Block from being processed

After setting everything up, giveBack() makes some API calls & returns processed data, wrapped by a Packages object:

$processed = $obj->giveBack();

At this point, there are three basic methods you can use:

  • data() returns raw data from lockfile for all used packages
  • pkgs() returns processed data for all used packages
  • packages() returns the names of all used packages
# Dump raw data
$raw = $obj->data();

# Process data
$processed = $obj->giveBack();

# Work with it
$pkgData = $processed->pkgs();

For convenience, there are methods to

  • list licenses & number of occurences: licenses()
  • group packages by license: byLicense()
$licenseData = $processed->licenses();
$groupedByLicense = $processed->byLicense();

Example

This example should get you started:

<?php

require_once('vendor/autoload.php');

use S1SYPHOS\Thx;

$pkgFile = 'path/to/composer.json';  # or 'package.json' for NPM / Yarn
$lockFile = 'path/to/composer.lock'  # or 'package-lock.json' for NPM / 'yarn.lock' for Yarn

try {
    $obj = new Thx($pkgFile, $lockFile);

    # Dump (raw) data extracted from lockfiles
    var_dump($obj->data());

    # Process data
    $processed = $obj->giveBack();

    # Dump package data
    var_dump($processed->pkgs())

    # Dump package names
    var_dump($processed->packages())

} catch (Exception $e) {
    # No dependencies found, file not found, ..
    echo $e->getMessage();
}

Roadmap

  • Add (more sophisticated) tests for now, they get the job done
  • Parse yarn v1 lockfiles
  • Gather information using public APIs
  • Custom Exceptions
  • Move data manipulation to uniform Packages class
  • Provide more (sorting/filtering) methods, eg ..
    • .. byLicense() = 'MIT' => [...], 'GPL v3' => [...] etc
    • .. byDownloads() = '2k' => [...], '1k' => [...] etc

Credits

Most of the helper functions were taken from Kirby's excellent toolkit package by Bastian Allgeier (who's just awesome, btw).

Happy coding!