PHPackages                             haianibrahim/tiktok-scraper-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. haianibrahim/tiktok-scraper-laravel

ActiveLibrary[API Development](/categories/api)

haianibrahim/tiktok-scraper-laravel
===================================

Laravel package for TikTok video scraping with clean API integration for Laravel 11.x, 12.x, and 13.x

v2.2.1(5d ago)031MITPHPPHP ^8.2

Since Jun 29Pushed 2w agoCompare

[ Source](https://github.com/haianibrahim/tiktok-scraper-laravel)[ Packagist](https://packagist.org/packages/haianibrahim/tiktok-scraper-laravel)[ RSS](/packages/haianibrahim-tiktok-scraper-laravel/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (10)Versions (3)Used By (0)

Laravel TikTok Scraper
======================

[](#laravel-tiktok-scraper)

A Laravel package that provides an easy way to scrape TikTok video, photo post, and user profile data directly into your Laravel application. This package wraps the [haianibrahim/tiktok-scraper](https://github.com/haianibrahim/tiktok-scraper) native package (v2.1+) and adds Laravel-specific features including caching, rate limiting, events, and comprehensive API endpoints.

Features
--------

[](#features)

- 🚀 **Laravel 11 & 12 Compatible** - Built for modern Laravel versions
- 🎬 **Video Scraping** - Extract metadata and engagement stats from video URLs
- 🖼️ **Photo Post Scraping** - Full support for TikTok photo (slideshow) posts
- 👤 **User Profile Scraping** - Fetch profile details from a username or profile URL
- 📦 **Easy Integration** - Simple service provider and facade
- 🔧 **Configurable** - Comprehensive configuration options
- 💾 **Caching Support** - Built-in caching with multiple drivers
- ⚡ **Rate Limiting** - Prevent API abuse with customizable rate limits
- 📊 **Statistics Tracking** - Monitor scraping performance and usage
- 🎯 **Event System** - Laravel events for scraping operations
- 🛡️ **Exception Handling** - Comprehensive error handling
- 🌐 **HTTP API** - Ready-to-use REST API endpoints
- 🧪 **Testing Support** - Full test suite included
- 📝 **Artisan Commands** - CLI tools for testing and management

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require haianibrahim/tiktok-scraper-laravel
```

### Laravel Auto-Discovery

[](#laravel-auto-discovery)

The package uses Laravel's auto-discovery feature, so the service provider will be automatically registered.

### Publish Configuration

[](#publish-configuration)

Publish the configuration file:

```
php artisan vendor:publish --provider="Hki98\LaravelTikTokScraper\TikTokScraperServiceProvider" --tag="config"
```

### Run Migrations

[](#run-migrations)

Publish and run the database migrations for logging:

```
php artisan vendor:publish --provider="Hki98\LaravelTikTokScraper\TikTokScraperServiceProvider" --tag="migrations"
php artisan migrate
```

Configuration
-------------

[](#configuration)

The configuration file is published to `config/tiktok-scraper.php`. Key configuration options include:

```
return [
    // HTTP Client Configuration
    'http_client' => [
        'timeout' => env('TIKTOK_SCRAPER_TIMEOUT', 30),
        'connect_timeout' => env('TIKTOK_SCRAPER_CONNECT_TIMEOUT', 10),
        'user_agent' => env('TIKTOK_SCRAPER_USER_AGENT', 'Mozilla/5.0...'),
        'headers' => [
            'Accept' => 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
            'Accept-Language' => 'en-US,en;q=0.5',
            'Accept-Encoding' => 'gzip, deflate',
            'Connection' => 'keep-alive',
        ],
    ],

    // Caching Configuration
    'cache' => [
        'enabled' => env('TIKTOK_SCRAPER_CACHE_ENABLED', true),
        'store' => env('TIKTOK_SCRAPER_CACHE_STORE', null),
        'ttl' => env('TIKTOK_SCRAPER_CACHE_TTL', 3600),
        'prefix' => env('TIKTOK_SCRAPER_CACHE_PREFIX', 'tiktok_scraper'),
    ],

    // Rate Limiting Configuration
    'rate_limiting' => [
        'enabled' => env('TIKTOK_SCRAPER_RATE_LIMIT_ENABLED', true),
        'max_attempts' => env('TIKTOK_SCRAPER_RATE_LIMIT_MAX_ATTEMPTS', 60),
        'decay_minutes' => env('TIKTOK_SCRAPER_RATE_LIMIT_DECAY_MINUTES', 1),
    ],
];
```

Usage
-----

[](#usage)

### Using the Facade

[](#using-the-facade)

```
use Hki98\LaravelTikTokScraper\Facades\TikTokScraper;

// Scrape a single video
$videoDetails = TikTokScraper::scrape('https://www.tiktok.com/@username/video/1234567890');

echo $videoDetails->description;
echo $videoDetails->username;
echo $videoDetails->views;

// Scrape a photo (slideshow) post - same method, same VideoDetails object
$photoPost = TikTokScraper::scrape('https://www.tiktok.com/@username/photo/1234567890');

echo $photoPost->userNickname;
echo $photoPost->likes;

// Scrape a user profile (accepts a bare username, @username, or profile URL)
$user = TikTokScraper::scrapeUser('scout2015');

echo $user->nickname;
echo $user->getFormattedFollowers(); // e.g. "9M"
echo $user->verified ? 'Verified' : 'Not verified';

// Scrape multiple videos
$videos = TikTokScraper::scrapeMultiple([
    'https://www.tiktok.com/@user1/video/1234567890',
    'https://www.tiktok.com/@user2/video/0987654321',
]);

// Validate input before scraping
if (TikTokScraper::isValidTikTokUrl($url)) {
    $videoDetails = TikTokScraper::scrape($url);
}

if (TikTokScraper::isValidUserInput($username)) {
    $user = TikTokScraper::scrapeUser($username);
}

// Cache management
TikTokScraper::clearCache();
TikTokScraper::clearUrlCache($url);
```

### Using Dependency Injection

[](#using-dependency-injection)

```
use Hki98\LaravelTikTokScraper\Contracts\TikTokScraperInterface;

class VideoController extends Controller
{
    public function __construct(
        private readonly TikTokScraperInterface $scraper
    ) {}

    public function scrape(Request $request)
    {
        $url = $request->input('url');

        try {
            $videoDetails = $this->scraper->scrape($url);
            return response()->json($videoDetails->toArray());
        } catch (TikTokScraperException $e) {
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }
}
```

### Video Details Object

[](#video-details-object)

The `VideoDetails` object (returned for both video and photo posts) contains the following information:

```
$videoDetails = TikTokScraper::scrape($url);

// Basic information
echo $videoDetails->videoId;
echo $videoDetails->description;
echo $videoDetails->canonicalUrl;
echo $videoDetails->thumbnail;

// User information
echo $videoDetails->username;
echo $videoDetails->userNickname;
echo $videoDetails->userId;
echo $videoDetails->getUserProfileUrl(); // https://www.tiktok.com/@username

// Statistics
echo $videoDetails->views;
echo $videoDetails->likes;
echo $videoDetails->comments;
echo $videoDetails->shares;
echo $videoDetails->favorites;

// Calculated metrics & helpers
echo $videoDetails->getEngagementRate();   // Percentage of views
echo $videoDetails->getTotalEngagement();  // likes + comments + shares + favorites
echo $videoDetails->getFormattedViews();   // e.g. "1.5M"
echo $videoDetails->getFormattedLikes();   // e.g. "35.1K"
echo $videoDetails->getEmbedUrl();

// Convert to array/JSON
$array = $videoDetails->toArray();
$json = $videoDetails->toJson();
```

### User Info Object

[](#user-info-object)

The `UserInfo` object is returned by `scrapeUser()`:

```
$user = TikTokScraper::scrapeUser('scout2015');

// Identity
echo $user->userId;
echo $user->secUid;
echo $user->username;
echo $user->nickname;
echo $user->signature;
echo $user->region;

// Avatars
echo $user->avatarThumb;
echo $user->avatarMedium;
echo $user->avatarLarger;

// Flags
echo $user->verified ? 'verified' : 'not verified';
echo $user->privateAccount ? 'private' : 'public';

// Counts
echo $user->followerCount;
echo $user->followingCount;
echo $user->heartCount;
echo $user->videoCount;

// Helpers
echo $user->getProfileUrl();        // https://www.tiktok.com/@username
echo $user->getFormattedFollowers(); // e.g. "9M"
echo $user->getFormattedHearts();    // e.g. "108.2M"

// Convert to array/JSON
$array = $user->toArray();
$json = $user->toJson();
```

Artisan Commands
----------------

[](#artisan-commands)

### Test Scraper

[](#test-scraper)

Test the scraper functionality:

```
php artisan tiktok-scraper:test https://www.tiktok.com/@username/video/1234567890
```

### Bulk Scraping

[](#bulk-scraping)

Scrape multiple URLs from a file:

```
# From file with JSON output
php artisan tiktok-scraper:bulk urls.txt --output=results.json

# From file with CSV output
php artisan tiktok-scraper:bulk urls.txt --output=results.csv --format=csv
```

### View Statistics

[](#view-statistics)

View scraping statistics:

```
# Show stats
php artisan tiktok-scraper:stats

# Clear stats
php artisan tiktok-scraper:stats --clear
```

### Cache Management

[](#cache-management)

Manage the cache:

```
# Clear all cache
php artisan tiktok-scraper:clear-cache

# Clear specific cache
php artisan tiktok-scraper:clear-cache --url="https://www.tiktok.com/@username/video/1234567890"

# Clear with confirmation
php artisan tiktok-scraper:clear-cache --force
```

HTTP API Endpoints
------------------

[](#http-api-endpoints)

The package provides ready-to-use API endpoints:

### Scrape Single Video

[](#scrape-single-video)

```
POST /api/tiktok-scraper/scrape
Content-Type: application/json

{
    "url": "https://www.tiktok.com/@username/video/1234567890",
    "use_cache": true
}
```

### Scrape User Profile

[](#scrape-user-profile)

```
POST /api/tiktok-scraper/user
Content-Type: application/json

{
    "user": "scout2015",
    "use_cache": true
}
```

The `user` field accepts a bare username, an `@username`, or a full profile URL.

### Bulk Scrape

[](#bulk-scrape)

```
POST /api/tiktok-scraper/bulk-scrape
Content-Type: application/json

{
    "urls": [
        "https://www.tiktok.com/@user1/video/1234567890",
        "https://www.tiktok.com/@user2/video/0987654321"
    ],
    "use_cache": true
}
```

### Validate URL

[](#validate-url)

```
POST /api/tiktok-scraper/validate
Content-Type: application/json

{
    "url": "https://www.tiktok.com/@username/video/1234567890"
}
```

### Get Statistics

[](#get-statistics)

```
GET /api/tiktok-scraper/stats
```

### Clear Cache

[](#clear-cache)

```
DELETE /api/tiktok-scraper/cache
```

### Health Check

[](#health-check)

```
GET /api/tiktok-scraper/health
```

Events
------

[](#events)

The package dispatches Laravel events for monitoring:

### VideoScraped Event

[](#videoscraped-event)

```
use Hki98\LaravelTikTokScraper\Events\VideoScraped;

// Listen for successful scrapes
Event::listen(VideoScraped::class, function (VideoScraped $event) {
    Log::info('Video scraped successfully', [
        'url' => $event->url,
        'video_id' => $event->videoDetails->videoId,
        'username' => $event->videoDetails->username,
    ]);
});
```

### UserScraped Event

[](#userscraped-event)

```
use Hki98\LaravelTikTokScraper\Events\UserScraped;

Event::listen(UserScraped::class, function (UserScraped $event) {
    Log::info('User scraped successfully', [
        'input' => $event->input,
        'user_id' => $event->userInfo->userId,
        'username' => $event->userInfo->username,
    ]);
});
```

### ScrapingFailed Event

[](#scrapingfailed-event)

```
use Hki98\LaravelTikTokScraper\Events\ScrapingFailed;

Event::listen(ScrapingFailed::class, function (ScrapingFailed $event) {
    Log::error('Scraping failed', [
        'url' => $event->url,
        'error' => $event->exception->getMessage(),
    ]);
});
```

### RateLimitHit Event

[](#ratelimithit-event)

```
use Hki98\LaravelTikTokScraper\Events\RateLimitHit;

Event::listen(RateLimitHit::class, function (RateLimitHit $event) {
    Log::warning('Rate limit hit', [
        'url' => $event->url,
    ]);
});
```

Exception Handling
------------------

[](#exception-handling)

The package provides specific exceptions for different error scenarios:

```
use Hki98\LaravelTikTokScraper\Exceptions\{
    TikTokScraperException,
    InvalidUrlException,
    HttpRequestException,
    EmptyResponseException,
    ParseException,
    RateLimitException
};

try {
    $videoDetails = TikTokScraper::scrape($url);
} catch (InvalidUrlException $e) {
    // Handle invalid URL or user input
} catch (RateLimitException $e) {
    // Handle rate limiting
} catch (HttpRequestException $e) {
    // Handle HTTP errors
} catch (EmptyResponseException $e) {
    // Handle empty responses
} catch (ParseException $e) {
    // Handle parsing errors
} catch (TikTokScraperException $e) {
    // Handle general scraper errors
}
```

Testing
-------

[](#testing)

Run the package tests:

```
composer test
```

Run tests with coverage:

```
composer test-coverage
```

Requirements
------------

[](#requirements)

- PHP 8.2 or higher
- Laravel 11.0 or 12.0
- GuzzleHTTP 7.8 or higher
- [haianibrahim/tiktok-scraper](https://github.com/haianibrahim/tiktok-scraper) 2.1 or higher (installed automatically)

Contributing
------------

[](#contributing)

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

Support
-------

[](#support)

If you find this package helpful, please consider starring the repository.

For issues and feature requests, please use the [GitHub issue tracker](https://github.com/haianibrahim/laravel-tiktok-scraper/issues).

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

If you discover a security vulnerability, please send an e-mail via the contact information in the composer.json file. All security vulnerabilities will be promptly addressed.

Credits
-------

[](#credits)

- [Haian Ibrahim](https://github.com/haianibrahim)
- Based on the original [tiktok-scraper](https://github.com/haianibrahim/tiktok-scraper) package
- All Contributors

###  Health Score

41

↑

FairBetter than 87% of packages

Maintenance97

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

5d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/205984087?v=4)[Haian Ibrahim](/maintainers/haianibrahim)[@haianibrahim](https://github.com/haianibrahim)

---

Top Contributors

[![haianibrahim](https://avatars.githubusercontent.com/u/205984087?v=4)](https://github.com/haianibrahim "haianibrahim (6 commits)")

---

Tags

apilaravellaravel-packagescrapersocial-mediatiktokvideoapilaravellaravel-packagevideoscrapersocial mediaTikTok

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/haianibrahim-tiktok-scraper-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/haianibrahim-tiktok-scraper-laravel/health.svg)](https://phpackages.com/packages/haianibrahim-tiktok-scraper-laravel)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[laravel/socialite

Laravel wrapper around OAuth 1 & OAuth 2 libraries.

5.7k108.5M885](/packages/laravel-socialite)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5021.9k](/packages/simplestats-io-laravel-client)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M132](/packages/laravel-pulse)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

816333.8k3](/packages/defstudio-telegraph)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)