README

Scrape basic details from public TikTok video posts, photo posts and user profiles in PHP. This is a cleaned-up, PSR‑4, PHP 8 rewrite using Guzzle and zero private APIs.

Features

• Public video posts (/video/): canonical URL, IDs, username, nickname, description, thumbnail and counters
• Public photo posts (/photo/): same normalized shape as videos
• Public user profiles: identity, avatars, bio, verification and follower/heart/video stats
• PSR‑4 autoloaded library with typed, immutable DTO output
• Pluggable Guzzle client for testing and timeouts
• No headless browser, no TikTok private API usage

Installation

Install via Composer:

composer require haianibrahim/tiktok-scraper

Quick Start

use GuzzleHttp\Client; // Or any ClientInterface
use Hki98\TikTok\TikTokScraper;

require __DIR__ . '/vendor/autoload.php';

$client = new Client();
$scraper = new TikTokScraper($client);

// Works for both video posts and photo posts
$details = $scraper->scrape('https://www.tiktok.com/@scout2015/video/6718335390845095173');

print_r($details->toArray());

Post output shape (VideoDetails):

• status: "ok"
• link
• user (nickname)
• username
• user_id
• video_id
• video_desc
• thumbnail
• views, likes, comments, shares, favorites

Scraping User Profiles

Fetch public profile information by bare username, @username, or a full profile URL:

use GuzzleHttp\Client;
use Hki98\TikTok\TikTokScraper;

require __DIR__ . '/vendor/autoload.php';

$scraper = new TikTokScraper(new Client());

$info = $scraper->scrapeUser('scout2015');
// Also valid: '@scout2015' or 'https://www.tiktok.com/@scout2015'

print_r($info->toArray());

Profile output shape (UserInfo):

• status: "ok"
• user_id, sec_uid, username, nickname
• signature (bio)
• avatar_thumb, avatar_medium, avatar_larger
• verified, private_account
• create_time, region
• follower_count, following_count, heart_count, video_count, digg_count, friend_count
• profile_url
• share_title, share_desc

API

• TikTokScraper::scrape(string $url): VideoDetails — video and photo posts
• TikTokScraper::scrapeUser(string $usernameOrUrl): UserInfo — user profiles
• VideoDetails::toArray(): array
• UserInfo::toArray(): array

Exceptions

• Base: Hki98\TikTok\Exception\TikTokScraperException (catch-all)
• Specific:
  • Hki98\TikTok\Exception\InvalidUrlException
  • Hki98\TikTok\Exception\HttpRequestException
  • Hki98\TikTok\Exception\EmptyResponseException
  • Hki98\TikTok\Exception\ParseException

Notes

• TikTok frequently changes HTML structure; this scraper parses the rehydration JSON in a script tag. If the key paths change, update the normalization method.
• Respect robots.txt and terms of service in your jurisdiction.

Development

• PHP 8.1+
• PSR‑12 coding style recommended
• Autoload: PSR‑4 under namespace Hki98\\TikTok (src/)

Run autoload dump after cloning:

composer dump-autoload

Credit

• Original author: Haian K. Ibrahim (https://github.com/haianibrahim)
• HTML parsing here is regex-based for one script tag; the bundled simple_html_dom.php is kept for historical context but not used by the new class.

License

GPL-3.0