O'Reilly

Using the GitHub API and PHP to Get Repository Information

By on  

GitHub is an awesome place to host your open source project code. MooTools, Prototype, and jQuery all use GitHub. As you probably know, the MooTools Forge requires your plugins be hosted on GitHub. The only problem with hosting all my MooTools plugins is that I lose traffic when I want people to see my code. Problem solved: use PHP, the GitHub API, and PHP Markdown to display files of my choice on my website.

Our goals with this code will be to:

  • Connect to GitHub via the API to retrieve repository information.
  • Retrieve the content of two files from the repository: a source file and the README.md Markdown file.
  • Cache the information for a given period of time to reduce the load on GitHub.
  • Use PHP Markdown to output a formatted README.md file.

I know that seems like a lot of work but you'll be amazed at how easy the process is.

PHP MarkDown

You may download PHP Markdown at Michel Fortin's website. It's simple and full of features.

The PHP

The first step is to build a PHP function that will connect to GitHub using cURL:

/* gets url */
function get_content_from_github($url) {
	$ch = curl_init();
	curl_setopt($ch,CURLOPT_URL,$url);
	curl_setopt($ch,CURLOPT_RETURNTRANSFER,1); 
	curl_setopt($ch,CURLOPT_CONNECTTIMEOUT,1);
	$content = curl_exec($ch);
	curl_close($ch);
	return $content;
}

Next we need to define a few settings:

/* static settings */
$plugin = 'Overlay';
$cache_path = $_SERVER['DOCUMENT_ROOT'].'/plugin-cache/';
$cache_file = $plugin.'-github.txt';
$github_json = get_repo_json($cache_path.$cache_file,$plugin);

The next step is to create another PHP function that grabs the repository information (JSON-encoded, because I love JSON) -- either fresh from GitHub (by first grabbing the most recent commit hash, then grabbing the contents of the two files) or our local cached information:

/* gets the contents of a file if it exists, otherwise grabs and caches */
function get_repo_json($file,$plugin) {
	//vars
	$current_time = time(); $expire_time = 24 * 60 * 60; $file_time = filemtime($file);
	//decisions, decisions
	if(file_exists($file) && ($current_time - $expire_time < $file_time)) {
		//echo 'returning from cached file';
		return json_decode(file_get_contents($file));
	}
	else {
		$json = array();
		$json['repo'] = json_decode(get_content_from_github('http://github.com/api/v2/json/repos/show/darkwing/'.$plugin),true);
		$json['commit'] = json_decode(get_content_from_github('http://github.com/api/v2/json/commits/list/darkwing/'.$plugin.'/master'),true);
		$json['readme'] = json_decode(get_content_from_github('http://github.com/api/v2/json/blob/show/darkwing/'.$plugin.'/'.$json['commit']['commits'][0]['parents'][0]['id'].'/Docs/'.$plugin.'.md'),true);
		$json['js'] = json_decode(get_content_from_github('http://github.com/api/v2/json/blob/show/darkwing/'.$plugin.'/'.$json['commit']['commits'][0]['parents'][0]['id'].'/Source/'.$plugin.'.js'),true);
		file_put_contents($file,json_encode($json));
		return $content;
	}
}

Once we've acquired the appropriate information, we output the information to screen:

/* build json */
if($github_json) {
	
	//get markdown
	include($_SERVER['DOCUMENT_ROOT'].'/wp-content/themes/walshbook3/PHP-Markdown-Extra-1.2.4/markdown.php');
	
	//build content
	$content = '

'.$github_json['repo']['repository']['description'].'

'; $content.= '

MooTools JavaScript Class

'.$github_json['js']['blob']['data'].'

'; $content.= trim(str_replace(array('',''),'',Markdown($github_json['readme']['blob']['data']))); }

That's all! Now I get the benefit of hosting my code on GitHub but displaying it on my own website. I've created a special WordPress template page to do so and recommend you do too!

Demo?

Visit my Projects page and click on the "Docs" link for any project. All of the information that comes up on individual project pages comes from GitHub. No more manual page creation!

Track.js Error Reporting

Upcoming Events

Recent Features

  • Animated 3D Flipping Menu with CSS

    CSS animations aren't just for basic fades or sliding elements anymore -- CSS animations are capable of much more.  I've showed you how you can create an exploding logo (applied with JavaScript, but all animation is CSS), an animated Photo Stack, a sweet...

  • 9 Mind-Blowing Canvas Demos

    The <canvas> element has been a revelation for the visual experts among our ranks.  Canvas provides the means for incredible and efficient animations with the added bonus of no Flash; these developers can flash their awesome JavaScript skills instead.  Here are nine unbelievable canvas demos that...

Incredible Demos

  • CSS Circles

    A while back I shared a clever technique for creating triangles with only CSS. Over the past year, I've found CSS triangles incredibly effective, especially when looking to create tooltips or design elements with a likewise pointer pattern. There's another common shape...

  • Create a 2 Column Layout with Flexbox

    Flexbox was supposed to be the pot of gold at the long, long rainbow of insufficient CSS layout techniques.  And the only disappointment I've experienced with flexbox is that browser vendors took so long to implement it.  I can't also claim to have pushed flexbox's limits, but...

Discussion

  1. Roy Sutton

    Very nice, exactly what I was looking for. I did notice that the last line of get_repo_json() should be return $json instead of return $content.

  2. Hi, nice article.
    I would love to try it, but your demo seems to fail.

  3. David

    Is there a way to get the contents of a private repository through php if you have a user name and password and permissions on the repository? Any direction how to go about it?

Wrap your code in <pre class="{language}"></pre> tags, link to a GitHub gist, JSFiddle fiddle, or CodePen pen to embed!

Recently on David Walsh Blog

  • Free Download: Font Bundle Featuring 17 Incredible Typefaces

    The only thing we love more than a good font, is a good free font. So we’ve combed the Web for some of our favorite free fonts, and gathered them here in a single download. You’ll find a variety of useful typefaces, from highly geometric designs...

  • OâReilly Velocity Conference â Amsterdam

    My favorite front-end conference has always been O'Reilly's Velocity Conference because the conference series has focused on one of the most undervalued parts of client side coding:  speed.  So often we're so excited that our JavaScript works that we forget that speed, efficiency, and performance are just as important. The next Velocity...

  • CanIUse Command Line

    Every front-end developer should be well acquainted with CanIUse, the website that lets you view browser support for browser features.  When people criticize my blog posts for not detailing browser support for features within the post, I tell them to check CanIUse:  always up to date, unlike...

  • Generating Alternative Stylesheets for Browsers Without @media

    If your CSS code is built with a mobile-first approach, it probably contains all the rules that make up the "desktop" view inside @media statements. That's great, but browsers that don't support media queries (IE 8 and below) will simply ignore them, ending up getting the...

  • Serve a Directory with PHP

    Many developers have a giggle at PHP, even looking down at the language, but let's be honest:  most of our blogs are powered by it (WordPress) and it's a great language to dabble around with.  I cut my teeth on PHP, though I prefer to avoid PHP these days. But...