Get the files

You can download a zip file and extract it

OR

if you use a version control client you can checkout the sources of the project. It will make it easier to keep the files up to date.

Git clone

Checkout sources with git client.
The following commands create a directory cdnorlocal below webroot and put all files there:

cd [webroot-directory]/[install-dir]/
git clone https://github.com/axelhahn/cdnorlocal.git [optional-name-of-subdir]

Leaving [optional-name-of-subdir] empty will create a subdir named "cdnorlocal"

Download

Get the latest version:
Download

Extract all files somewhere below webroot on your webserver. You can put to any subdirectory. It is not a must to have it in the webroot.

Basics

Introduction

In the ./classes/ directory you find 2 classes.

• cdnorlocal.class.php
  This file you can copy to the classes directory in your project. Then follow the first examples.
• cdnorlocal-admin.class.php
  This class is needed by the admin (only). It handles API requests, download, handling of local libraries.

first example: load jQuery

In your webapp you only need the single file "cdnorlocal.class.php"

What you need to know is that the structure of all libraries is
[name of the lib]/ [version] / [path+filename]

Because we don't have a local copy at of it it will be loaded from cdnjs.com.
With the method getHtmlInclude([relative path]) you get html code to load a css or js file (put it int the header of the html document).

	// load the class
	require_once('[PATH]/cdnorlocal.class.php');
	
	// init class
	$oCdn = new axelhahn\cdnorlocal();
	
	// load a js or css file with getHtmlInclude
	echo $oCdn->getHtmlInclude("jquery/3.2.1/jquery.min.js");

It returns:

	<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>

Customized link or script tag

The method getHtmlInclude returns very basic html code.
To customize it or you want to handle a non CSS or JS file use the method getFullUrl(). It returns the url only.

	$oCdn = new axelhahn\cdnorlocal();
	echo '<script src="'.$oCdn->getFullUrl("jquery/3.2.1/jquery.min.js").'" [... your attributes ...]></script>';

	<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.min.js" [... your attributes ...]></script>

How to find a library

You see in the examples that you always need to build the structure. Therefor you need to know the valid libraries, its versions and files.

There are two possibilities to do it:

1. visit cdnjs.com
   There you can search and browse for several thousand libraries. You can copy & paste the path from here.
2. use the included admin webgui - open the ./admin/ with your browser i.e. http://localhost/cdnorlocal/admin/
   See the next chapter.

Admin

The tool is shipped with a webgui. You need to open ./admin/ with your browser i.e. http://localhost/cdnorlocal/admin/
With this webgui you can

• search for libraries on cdnjs.com and view details of it (you get the same results - it uses API of cdnjs.com)
• download any version of any library into ./vendor/ dir
  Remark: A limitation: The downloader works fine for libs with a few files. For larger libraries it is inefficient because it downloads file by file with 50 multicurl requests.
• downloaded versions will be compared with current version. Outdated versions will be marked. So you have a version checker and have a control control over possible updates.
• delete a downloaded library

Use local library

You need to download all files of a library and put it below the ./vendor/ directory.
The structure must be ./vendor/ [name of the lib] / [version] / [path+filename]

I suggest to use the admin gui to dowload the libraries.

If the local structure of a needed library exists then the getFullUrl() and getHtmlInclude() return a path of a current domain.

Now you may say ... how can the class match a local directory to a url?

If you initialize with the defaults:

	$oCdn = new axelhahn\cdnorlocal();

... then the default url is "/vendor" and the path "[webroot]/vendor".
You can customize the location and url prefix:

	$oCdn = new axelhahn\cdnorlocal(
		'vendordir' => __DIR__ . '/../vendor_dir',
		'vendorurl' => '/vendor_dir'
	);

OR
another posiibility is to use a single parameter: set a relative path.

	$oCdn = new axelhahn\cdnorlocal(
		'vendorrelpath'=>'../vendor/cache',
	);

Use several libraries

Mostly a web app uses several classes. You can set its name and version in a flat array:

	$oCdn->setLibs(array(
		"font-awesome/5.8.1",
		"jquery/3.4.0"
	));

The advantages are:

• You can use a lib with the name only. So it will be easier to maintain library version updates on a single place.

  echo $oCdn->getHtmlInclude($oCdn->getLibRelpath('jquery')."/jquery.min.js") . "\n";

• With getLibs you can detect if your libs exist locally. Or if you update a version you can verify if an locally existing lib is still used.
  

  print_r($oCdn->getLibs(true));

  Array
  (
      [font-awesome/5.8.1] => Array
          (
              [lib] => font-awesome
              [version] => 5.8.1
              [relpath] => font-awesome/5.8.1
              [islocal] => 
              [isunused] => 
              [files] => Array
                  (
                  )
  
          )
  
      [jquery/3.4.0] => Array
          (
              [lib] => jquery
              [version] => 3.4.0
              [relpath] => jquery/3.4.0
              [islocal] => 
              [isunused] => 
              [files] => Array
                  (
                  )
  
          )
  
  )