Aimeos Laravel

aimeos/aimeos-laravel

제출자 Laravel Korea Discovery Bot

최신 v2026.04.1라이센스 MIT

결제·구독

초고속 온라인 쇼핑몰, 마켓플레이스, 복잡한 B2B 프로젝트를 위한 클라우드 네이티브, API 우선 방식의 Laravel 이커머스 패키지로, AI가 통합되어 있습니다

GitHub

Aimeos Laravel 이커머스 패키지

:star: GitHub에서 Star를 눌러주시면 큰 힘이 됩니다! 😀

Aimeos는 전문적이고 기능이 풍부하며 매우 빠른 Laravel 이커머스 패키지입니다! 기존에 운영 중인 Laravel 애플리케이션에 5분 안에 설치할 수 있으며, 필요에 맞게 자유롭게 수정, 확장, 오버라이드, 커스터마이징할 수 있습니다.

주요 기능

Aimeos는 다음과 같은 기능을 갖춘 풀 스펙 이커머스 패키지입니다:

멀티 벤더, 멀티 채널, 멀티 창고 지원
상품 1개부터 10억 개 이상까지 확장 가능
최대 20ms까지 끌어올린 극한의 처리 속도
무제한 벤더를 수용하는 멀티 테넌트 이커머스 SaaS 구축 지원
번들, 바우처, 가상 상품, 옵션형(구성 가능) 상품, 커스텀/이벤트 상품 지원
정기 결제 기반 구독 서비스
100개 이상의 결제 게이트웨이 연동
RTL(우측에서 좌측으로 읽는 언어) 완전 지원 (프런트엔드/백엔드 모두)
구간별(수량 기준) 가격 정책 기본 제공
고객/그룹별 가격 설정 확장 기능
할인 및 바우처 지원
유연한 장바구니 규칙 시스템
완전한 기능을 갖춘 관리자 백엔드
세련된 관리자 대시보드
설정 가능한 상품 데이터셋
jsonapi.org 표준 기반 JSON REST API
관리 기능을 위한 GraphQL API
완전 모듈화된 구조
뛰어난 설정 유연성과 확장성
수백만 벤더 규모의 마켓플레이스 확장 지원
리치 스니펫을 포함한 완벽한 SEO 최적화
30개 이상 언어로 번역 지원
AI 기반 텍스트 번역
스마트폰과 태블릿에 최적화된 반응형 화면
검증된 안전한 구현
높은 코드 품질

... 그 외 더 많은 Aimeos 기능 보기

지원 언어:

데모도 함께 확인해 보세요:

다른 배포판도 고려해보세요

완전한 쇼핑몰 애플리케이션이 필요하다면

새 애플리케이션을 만들거나 Aimeos를 테스트해보고 싶다면 Aimeos 샵 배포판(shop distribution)을 추천합니다. 빠른 시작에 필요한 모든 것이 포함되어 있어, 5분 이내에 완전히 동작하는 온라인 쇼핑몰을 만들 수 있습니다:

:star: Aimeos 샵 배포판

헤드리스(Headless) 구성이 필요하다면

Aimeos의 HTML 프런트엔드 없이 직접 SPA(싱글 페이지 애플리케이션)나 PWA(프로그레시브 웹 앱)를 구축하고 싶다면 Aimeos 헤드리스 배포판이 적합합니다:

:star: Aimeos 헤드리스 배포판

지원 버전

현재 Aimeos Laravel 패키지는 2024.10 버전 이상을 완전히 지원합니다:

LTS 릴리스: 2025.10 이상 (Laravel 10.x, 11.x, 12.x)
이전 LTS 릴리스: 2024.10 이상 (Laravel 10.x, 11.x)

메이저 버전 간 업그레이드를 진행하려면 업그레이드 가이드를 반드시 참고하세요!

요구 사항

Aimeos 샵 배포판은 다음 환경을 필요로 합니다:

Linux/Unix, WAMP/XAMP 또는 macOS 환경
PHP 8.1 이상
MySQL 5.7.8 이상, MariaDB 10.2.2 이상, PostgreSQL 9.6 이상, SQL Server 2019 이상
웹 서버(Apache, Nginx 또는 테스트용 PHP 내장 서버)

필요한 PHP 확장 모듈이 누락되어 있다면 composer가 부족한 의존성을 알려줍니다.

메이저 버전 간 업그레이드를 진행하려면 업그레이드 가이드를 반드시 참고하세요!

데이터베이스

애플리케이션 디렉터리의 .env 파일을 설정하기 전에 먼저 데이터베이스를 생성해 두어야 합니다. 간혹 .env 설정만으로는 데이터베이스 연결에 실패하는 예외가 발생하는 경우가 있는데, 이럴 때는 ./config/shop.php 파일의 resource/db 섹션에도 동일한 데이터베이스 접속 정보를 추가해주세요!

MySQL 5.7.8 또는 MariaDB 10.2.2 미만 버전을 사용 중이라면 다음과 같은 오류가 발생할 수 있습니다.

Specified key was too long; max key length is 767 bytes

이 문제를 피하려면, 이미 생성된 테이블이 있다면 삭제한 뒤 ./config/database.php의 charset/collation 설정을 아래와 같이 변경하고 Aimeos를 다시 설치하세요:

'connections' => [
    'mysql' => [
        // ...
        'charset' => 'utf8',
        'collation' => 'utf8_unicode_ci',
        // ...
    ]
]

주의: MySQL 서버가 기본적으로 InnoDB 테이블을 생성하도록 설정되어 있는지도 확인하세요. MyISAM 테이블은 외래 키 제약 조건 오류를 일으키며 동작하지 않습니다!

MySQL 이외의 데이터베이스 서버를 사용하고 싶다면 지원되는 데이터베이스 서버 문서에서 각 서버별 세부 설정 방법을 확인하세요. 다음 데이터베이스가 지원됩니다:

MySQL, MariaDB (완전 지원)
PostgreSQL (완전 지원)
SQL Server (완전 지원)

.env 파일에는 반드시 지원되는 데이터베이스 서버를 지정해야 합니다. 예시:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=aimeos
DB_USERNAME=root
DB_PASSWORD=

주의: Laravel 기본 설정인 SQLite 데이터베이스는 지원하지 않습니다!

설치

Aimeos Laravel 온라인 쇼핑몰 패키지는 Composer 기반 라이브러리입니다. 기존 Laravel 애플리케이션의 루트 디렉터리에서 Composer 2.1 이상을 사용해 손쉽게 설치할 수 있습니다:

wget https://getcomposer.org/download/latest-stable/composer.phar -O composer

그런 다음, Laravel 기본 스켈레톤 애플리케이션의 composer.json 파일에 다음 내용을 추가합니다:

    "prefer-stable": true,
    "minimum-stability": "dev",
    "require": {
        "aimeos/aimeos-laravel": "~2025.10",
        ...
    },
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force",
            "@php artisan vendor:publish --tag=public --ansi",
            "\\Aimeos\\Shop\\Composer::join"
        ],
        ...
    }

이후 다음 명령어로 Aimeos 샵 패키지를 설치합니다:

php composer update -W

마지막으로, 아래 Artisan 명령어들을 실행해 Aimeos 설치(또는 업데이트)를 완료합니다:

php artisan vendor:publish --tag=config --tag=publicphp artisan migratephp artisan aimeos:setup --option=setup/default/demo:1

운영(production) 환경이거나 데모 데이터를 설치하고 싶지 않다면 --option=setup/default/demo:1 옵션을 생략하세요.

인증

Laravel의 인증 스타터 키트 중 하나를 반드시 설정해야 합니다. Laravel Breeze가 가장 간단하며, Jetstream을 사용해도 무방합니다.

composer require laravel/breeze
php artisan breeze:install
npm install && npm run build # 위 명령어가 자동으로 실행하지 않는 경우에만 직접 실행

Laravel Breeze는 설치 과정에서 몇 가지 질문을 합니다. 가장 중요한 것은 사용할 스택 종류인데, 가장 쉬운 방법인 "Blade"를 선택하고 나머지 항목은 기본값을 그대로 사용하세요.

Breeze는 ./routes/web.php에 /profile 라우트를 추가하는데, 이 라우트가 aimeos_shop_account 라우트와 충돌할 수 있습니다. aimeos_shop_account 라우트가 없다는 예외가 발생하지 않도록, ./routes/web.php 파일에서 해당 URL을 /profile에서 /profile/me로 변경하세요:

Route::middleware('auth')->group(function () {
    Route::get('/profile/me', [ProfileController::class, 'edit'])->name('profile.edit');
    Route::patch('/profile/me', [ProfileController::class, 'update'])->name('profile.update');
    Route::delete('/profile/me', [ProfileController::class, 'destroy'])->name('profile.destroy');
});

더 자세한 내용은 Laravel 공식 문서를 참고하세요:

인증(권한) 설정하기

마지막으로, App\Providers\AppServiceProvider 클래스의 boot() 메서드를 확장하여 app/Providers/AppServiceProvider.php에 "admin" 권한을 어떻게 판별할지 정의하는 코드를 추가해야 합니다:

    public function boot()
    {
        // 기존 코드는 그대로 둡니다

        \Illuminate\Support\Facades\Gate::define('admin', function($user, $class, $roles) {
            if( isset( $user->superuser ) && $user->superuser ) {
                return true;
            }
            return app( '\Aimeos\Shop\Base\Support' )->checkUserGroup( $user, $roles );
        });
    }

계정 생성하기

다음 단계로 넘어가기 전에 인증 설정이 제대로 동작하는지 확인해보세요. Aimeos 관리자 화면에 로그인할 수 있도록 Laravel 애플리케이션에 관리자 계정을 생성합니다:

php artisan aimeos:account --super <email>

여기서 이메일 주소는 로그인 시 사용하는 아이디이며, 해당 계정은 프런트엔드 로그인에도 그대로 사용할 수 있습니다. 계정을 안전하게 보호하기 위해 명령어 실행 시 비밀번호를 입력하라는 안내가 표시됩니다. --super(모든 권한) 대신 --admin, --editor, --api 옵션을 사용하면 제한된 권한을 가진 계정도 만들 수 있습니다.

MCP 브리지

Aimeos는 공식 Laravel MCP 서버를 통해 관리 도구를 외부에 노출할 수 있습니다. 이 트랜스포트는 선택 사항이므로 MCP를 사용하지 않는 애플리케이션이나 Laravel 10 애플리케이션은 SDK 없이도 정상 동작합니다. 지원되는 Laravel 버전을 사용 중이라면 애플리케이션에 다음과 같이 설치합니다:

composer require laravel/mcp:^0.9

config/shop.php에서 엔드포인트를 활성화하고, 애플리케이션에서 사용 중인 토큰 가드로 보호하세요. 아래 예시는 Laravel Sanctum을 사용하는 경우입니다:

'guards' => [
    'mcp' => 'sanctum',
],
'routes' => [
    'mcp' => [
        'prefix' => 'admin/{site}/mcp',
        'middleware' => ['api', 'auth:sanctum'],
    ],
],

이렇게 설정하면 MCP 엔드포인트가 /admin/<site>/mcp 경로에서 제공됩니다. 이 라우트 설정과 laravel/mcp 패키지가 모두 준비되기 전까지는 비활성화된 상태로 유지됩니다. 인증 없이 절대 활성화하지 마세요. 이 서버는 관리자 권한의 읽기/쓰기 작업을 그대로 노출합니다.

이 브리지는 서버를 시작하기 전에 Laravel의 일반적인 admin 게이트를 먼저 적용합니다. 각 도구는 입력값을 검증하는 동시에 아래의 admin/mcp/resource 설정에 지정된 Aimeos 권한도 함께 확인합니다. 슈퍼유저는 모든 도구에 접근할 수 있으며, 제한된 관리자·편집자·API 계정에는 리소스별 권한을 명시적으로 부여해야 합니다.

설정

이미지가 올바르게 표시되도록 하려면 .env 파일의 APP_URL 값을 실제 서비스 URL로 맞춰야 합니다. 예시:

APP_URL=http://127.0.0.1:8000

주의: .env 파일에서 Laravel의 세션 드라이버가 반드시 file로 설정되어 있는지 확인하세요! 그렇지 않으면 장바구니에 담은 상품이 제대로 저장되지 않습니다!

SESSION_DRIVER=file

./public 디렉터리에 웹 서버의 쓰기 권한이 없다면 다음 디렉터리를 미리 생성해야 합니다:

mkdir public/aimeos public/vendor
chmod 777 public/aimeos public/vendor

운영 환경에서는 부여하는 권한을 더 세밀하게 제한하는 것이 좋습니다!

테스트

이제 브라우저에서 카탈로그 목록 페이지를 열어볼 차례입니다. 빠르게 테스트해보려면 Laravel에 내장된 웹 서버를 사용하면 됩니다. 애플리케이션의 최상위 디렉터리에서 다음 명령어를 실행하세요:

php artisan serve

프런트엔드

브라우저에서 다음 주소로 접속해 쇼핑몰 목록 페이지를 확인합니다:

http://127.0.0.1:8000/shop/search

참고: Aimeos 패키지를 통합하면 /shop이나 /admin 같은 라우트가 Laravel 애플리케이션에 추가되지만, 홈페이지(/)는 그대로 유지됩니다! 홈페이지에도 Aimeos를 적용하고 싶다면 ./routes/web.php에서 / 라우트를 다음 코드로 교체하세요:

Route::group(['middleware' => ['web']], function () {
    Route::get('/', '\Aimeos\Shop\Controller\CatalogController@homeAction')->name('aimeos_home');
});

멀티 벤더 구성이 필요하다면 다중 쇼핑몰 운영 문서를 참고하세요.

위 설정을 적용하면 홈페이지에 Aimeos의 카탈로그 홈 컴포넌트가 표시되어, 아래와 같이 세련된 쇼핑몰 홈페이지를 확인할 수 있습니다:

백엔드

앞서 안내한 대로 내장 PHP 웹 서버(php artisan serve)를 실행한 상태라면, 이제 브라우저에서 아래 주소를 열어보세요:

http://127.0.0.1:8000/admin

새로 만든 계정의 이메일 주소와 비밀번호를 입력하고 "Login" 버튼을 누릅니다. 만약 관리자 화면으로 자동 리디렉션되지 않는다면(이는 Laravel 문서에 따라 어떤 인증 코드를 작성했는지에 따라 달라질 수 있습니다), /admin 주소로 다시 접속해보세요.

주의: 이미 관리자가 아닌 일반 사용자로 로그인되어 있다면 관리자 로그인이 동작하지 않습니다! Laravel은 먼저 로그아웃을 해야만 다른 계정으로 다시 로그인할 수 있도록 요구합니다.

참고 사항

개발 편의를 위해서는 콘텐츠 캐시를 사용하지 않도록 설정하는 것이 좋습니다. Laravel 애플리케이션의 config/shop.php 파일 하단에 다음 내용을 추가하면 됩니다:

    'madmin' => [
        'cache' => [
            'manager' => [
                'name' => 'None',
            ],
        ],
    ],

라이선스

Aimeos Laravel 패키지는 MIT 라이선스 조건에 따라 배포되며 무료로 사용할 수 있습니다.